<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 10.13.0 -",
    "tvOS: 15.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "PhotoKit",
  "identifier" : "/documentation/Photos/PHCloudIdentifier",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Photos"
    ],
    "preciseIdentifier" : "c:objc(cs)PHCloudIdentifier"
  },
  "title" : "PHCloudIdentifier"
}
-->

# PHCloudIdentifier

An object that identifies an asset or collection that syncs through iCloud Photos.

```
class PHCloudIdentifier
```

## Overview

A cloud identifier is a type of identifier that behaves like a local identifier. Use cloud identifiers to identify objects that sync across devices through iCloud Photos. You can store, sync, and use cloud identifiers with devices synced with an iCloud account. You’re also able to use secure coding to encode and decode cloud identifiers.

A local identifier is valid for referring to objects only in the context of a local device. These objects include [`PHAsset`](/documentation/Photos/PHAsset), [`PHAssetCollection`](/documentation/Photos/PHAssetCollection), and [`PHCollectionList`](/documentation/Photos/PHCollectionList).

Because a cloud identifier is universal, you can use it on any iCloud-synced device. Convert the cloud identifier back to a local identifier and perform a fetch to find the equivalent object on that device. Perform batch lookups of identifiers using [`localIdentifierMappingsForCloudIdentifiers:`](/documentation/Photos/PHPhotoLibrary/localIdentifierMappingsForCloudIdentifiers:) and [`cloudIdentifierMappingsForLocalIdentifiers:`](/documentation/Photos/PHPhotoLibrary/cloudIdentifierMappingsForLocalIdentifiers:).

```swift
// Get the local identifier mappings for the cloud identifiers.
let identifierMappings = library.localIdentifierMappings(for: assetCloudIdentifiers)
```

Retrieving identifier mappings can be an expensive operation, so perform lookups sparingly. If a lookup fails, inspect the error property on [`PHCloudIdentifierMapping`](/documentation/Photos/PHCloudIdentifierMapping) or [`PHLocalIdentifierMapping`](/documentation/Photos/PHLocalIdentifierMapping) for details. See [`PHPhotosError.Code`](/documentation/Photos/PHPhotosError-swift.struct/Code) for additional error details.

```swift
// Iterate over the cloud identifiers and add or handle missing local identifiers.
for cloudIdentifier in assetCloudIdentifiers {
    guard let identifierMapping = identifierMappings[cloudIdentifier] else {
        print("Failed to find a mapping for \(cloudIdentifier).")
        continue
    }

    // Track the local identifier if it exists.
    if let localIdentifier = identifierMapping.localIdentifier {
        localIdentifiers.append(localIdentifier)
    } else if let error = identifierMapping.error as? PHPhotosError {
        switch error.code {
        case .identifierNotFound:
            // Skip the missing or deleted assets.
            print("Failed to find the local identifier for \(cloudIdentifier). \(error.localizedDescription))")
        case .multipleIdentifiersFound:
            // Prompt the user to resolve the cloud identifier that matched multiple assets.
            print("Found multiple local identifiers for \(cloudIdentifier). \(error.localizedDescription)")
            if let selectedLocalIdentifier = promptUserForPotentialReplacement(with: error.userInfo[PHLocalIdentifiersErrorKey]) {
                localIdentifiers.append(selectedLocalIdentifier)
            }
        default:
            print("Encountered an unexpected error looking up the local identifier for \(cloudIdentifier). \(error.localizedDescription)")
        }
    }
}

// Fetch assets using the found identifiers.
let mappedAssets = PHAsset.fetchAssets(withLocalIdentifiers: localIdentifiers, 
                                       options: nil)
```

## Topics

### Using Cloud Identifiers

[`init(stringValue:)`](/documentation/Photos/PHCloudIdentifier/init(stringValue:))

Deserializes a cloud identifier from its string value.

[`stringValue`](/documentation/Photos/PHCloudIdentifier/stringValue)

A string version of the cloud identifier to use in serialization.

[`notFound`](/documentation/Photos/PHCloudIdentifier/notFound)

The global identifier used in an array slot for items that couldn’t be found.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)