README.md

A simple, stable user identifier across devices

StableID is a simple package that helps you keep a stable user identifier across devices by leveraging iCloud Key Value Store).

It's useful for services like RevenueCat, where you may want to maintain a consistent user identifier to allow users to access their purchases across their devices, but you don't want to have a complete account system or use anonymous identifiers.

StableID persists across all devices of a user's iCloud account.

📦 Installation

Add this repository as a Swift package.

https://github.com/codykerns/StableID

ℹ️ Before using StableID

In order to use StableID, you'll need to add the iCloud capability to your target and enable Key-value storage:

🛠️ Configuration

Initialize StableID:

StableID.configure()

By default, StableID will look for any other StableID identifier in iCloud or local user defaults - otherwise, it will generate a new identifier.

If you want to provide a custom identifier to force the client to be set to a specific identifier and update iCloud:

StableID.configure(id: <optional_user_id>)

Call StableID.isConfigured to see if StableID has already been configured.

Changing identifiers

To change identifiers, call:

StableID.identify(id: <new_user_identifier>)

Receiving updates

To receive updates when a user identifier changes (for example from detecting a change from another iCloud device), configure a delegate:

// call after configuring StableID
StableID.set(delegate: MyClass())

class MyClass: StableIDDelegate {
    func willChangeID(currentID: String, candidateID: String) -> String? {
        // called before StableID changes IDs, it gives you the option to return the proper ID
    }
    
    func didChangeID(newID: String) {
        // called once the ID changes
    }
}

Custom ID Generators

By default, StableID uses a standard IDGenerator that generates simple UUIDs.

If you want any generated identifiers to follow a certain pattern, you can implement a custom ID generator by conforming to IDGenerator and implementing generateID():

struct MyCustomIDGenerator: IDGenerator {
    func generateID() -> String {
        // do something custom
        return myGeneratedID
    }
}

Then pass the generator as part of the configure method:

StableID.configure(idGenerator: MyCustomIDGenerator())

Built-in generators

• StableID.StandardGenerator: Standard UUIDs
• StableID.ShortIDGenerator: 8-character alphanumeric IDs

📚 Examples

Coming soon

📙 License

MIT