DITIdentity

@interface DITIdentity : NSObject

Used to identify a given peer in your network. In practice a peer may be a user, a device, or it might be some other entity in your system.

  • The type of the identity.

    Declaration

    Objective-C

    @property (nonatomic, readonly) enum DITIdentityType type;
  • The app ID.

    Use this to ensure that connections between devices are only established if they share the same app ID.

    Note that this will not be set for all identity types.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *appID;
  • The site ID.

    Use this to identity different users or devices. Site IDs are persisted between sessions.

    Site IDs should be unique and not reused by different users or devices.

    Note that this will not be set to a meaningful value for all identity types. 0 will represent an unset value.

    Declaration

    Objective-C

    @property (nonatomic, readonly) uint64_t siteID;
  • If true, sync with Ditto Cloud will be auto-configured.

    Note that this will not be set to a meaningful value for all identity types. false will represent an unset value.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL enableDittoCloudSync;
  • A base64 encoded DER representation of a private key, which is shared between devices for a single app.

    Note that this will not be set for all identity types.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSURL *customAuthURL;
  • A base64 encoded DER representation of a private key, which is shared between devices for a single app.

    Note that this will not be set for all identity types.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *sharedKey;
  • A base64 encoded string representation of a certificate bundle.

    Note that this will not be set for all identity types.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) NSString *certificateConfig;
  • Creates an OfflinePlayground identity suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)init;

    Return Value

    The default OfflinePlayground identity.

  • Deprecated

    use initOfflinePlayground instead.

    Creates a development identity suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initDevelopment;

    Return Value

    The default development identity.

  • Deprecated

    use initOfflinePlayground instead.

    Creates a development identity with the provided site ID and the default app ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initDevelopmentWithSiteID:(uint64_t)siteID;

    Parameters

    siteID

    the site ID of the peer.

    Return Value

    A development identity using the default app ID and the provided site ID.

  • Deprecated

    use initOfflinePlayground instead.

    Creates a development identity with the provided app ID and a random site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initDevelopmentWithAppID:(nonnull NSString *)appID;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    Return Value

    A development identity using the provided app ID and a random site ID.

  • Deprecated

    use initOfflinePlayground instead.

    Creates a development identity with the provided app ID and a random site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initDevelopmentWithAppID:(nonnull NSString *)appID
                                persistenceDirectory:(nullable NSURL *)directory;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    A development identity using the provided app ID and a random site ID.

  • Deprecated

    use initOfflinePlayground instead.

    Creates a development identity with the provided app ID and provided site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initDevelopmentWithAppID:(nullable NSString *)appID
                                              siteID:(uint64_t)siteID;

    Parameters

    appID

    an optional UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    siteID

    the site ID of the peer.

    Return Value

    A development identity using either the provided app ID or the default one, and the provided site ID.

  • Deprecated

    use initOfflinePlayground instead.

    Creates a development identity with the provided app ID and provided site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initDevelopmentWithAppID:(nullable NSString *)appID
                                              siteID:(uint64_t)siteID
                                persistenceDirectory:(nullable NSURL *)directory;

    Parameters

    appID

    an optional UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    siteID

    the site ID of the peer.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    A development identity using either the provided app ID or the default one, and the provided site ID.

  • Creates an OfflinePlayground identity suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOfflinePlayground;

    Return Value

    The default OfflinePlayground identity.

  • Creates an OfflinePlayground identity with the provided site ID and the default app ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOfflinePlaygroundWithSiteID:(uint64_t)siteID;

    Parameters

    siteID

    the site ID of the peer.

    Return Value

    An OfflinePlayground identity using the default app ID and the provided site ID.

  • Creates an OfflinePlayground identity with the provided app ID and a random site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOfflinePlaygroundWithAppID:
        (nonnull NSString *)appID;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    Return Value

    An OfflinePlayground identity using the provided app ID and a random site ID.

  • Creates an OfflinePlayground identity with the provided app ID and a random site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOfflinePlaygroundWithAppID:(nonnull NSString *)appID
                                      persistenceDirectory:
                                          (nullable NSURL *)directory;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    An OfflinePlayground identity using the provided app ID and a random site ID.

  • Creates an OfflinePlayground identity with the provided app ID and provided site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOfflinePlaygroundWithAppID:
                                (nullable NSString *)appID
                                                    siteID:(uint64_t)siteID;

    Parameters

    appID

    an optional UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    siteID

    the site ID of the peer.

    Return Value

    An OfflinePlayground identity using either the provided app ID or the default one, and the provided site ID.

  • Creates an OfflinePlayground identity with the provided app ID and provided site ID. The identity created will be suitable to develop peer-to-peer apps with no cloud connection. This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)
        initOfflinePlaygroundWithAppID:(nullable NSString *)appID
                                siteID:(uint64_t)siteID
                  persistenceDirectory:(nullable NSURL *)directory;

    Parameters

    appID

    an optional UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    siteID

    the site ID of the peer.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    An OfflinePlayground identity using either the provided app ID or the default one, and the provided site ID.

  • Deprecated

    use initOnlineWithAuthenticationWithAppID instead.

    Creates an Online identity.

    Online identities should be used when running Ditto in secure production mode, logging on to Ditto Cloud, or using an on-premises authentication server. User permissions are centrally managed. Sync will not work until a successful login has occurred.

    The only required configuration is the application’s UUID, which can be found on the Ditto portal where the app is registered, and an authentication callback. If you want to configure a custom auth URL or specify that you don’t want cloud sync to be used then use one of the other initOnline-prefixed methods.

    By default cloud sync is enabled. This means the SDK will sync to a Big Peer in Ditto’s cloud when an internet connection is available. This is controlled by the enableDittoCloudSync parameter found in the other initOnline-prefixed methods. If true (default), a suitable wss:// URL will be added to the TransportConfig. To prevent cloud sync, or to specify your own URL later, pass false.

    Authentication requests are handled by Ditto’s cloud by default, configured in the portal at https://portal.ditto.live.

    To use a different or on-premises authentication service, use the appropriate initOnline-prefixed method and pass a custom HTTPS base URL as the customAuthURL parameter.

    Declaration

    Objective-C

    - (nonnull instancetype)initOnlineWithAppID:(nonnull NSString *)appID
                         authenticationDelegate:
                             (nonnull id<DITAuthenticationDelegate>)
                                 authenticationDelegate;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    authenticationDelegate

    a handler for when Ditto requires (re)authentication.

    Return Value

    An Online identity suitable for a production Ditto deployment.

  • Deprecated

    use initOnlineWithAuthenticationWithAppID instead.

    Creates an Online identity.

    Online identities should be used when running Ditto in secure production mode, logging on to Ditto Cloud, or using an on-premises authentication server. User permissions are centrally managed. Sync will not work until a successful login has occurred.

    The only required configuration is the application’s UUID, which can be found on the Ditto portal where the app is registered, and an authentication callback. If you don’t want/need to provide a value for enableDittoCloudSync then use one of the other initOnline-prefixed methods.

    By default cloud sync is enabled. This means the SDK will sync to a Big Peer in Ditto’s cloud when an internet connection is available. This is controlled by the enableDittoCloudSync parameter. If true (default), a suitable wss:// URL will be added to the TransportConfig. To prevent cloud sync, or to specify your own URL later, pass false.

    Authentication requests are handled by Ditto’s cloud by default, configured in the portal at https://portal.ditto.live.

    To use a different or on-premises authentication service, pass a custom HTTPS base URL as the customAuthURL parameter.

    Declaration

    Objective-C

    - (nonnull instancetype)initOnlineWithAppID:(nonnull NSString *)appID
                         authenticationDelegate:
                             (nonnull id<DITAuthenticationDelegate>)
                                 authenticationDelegate
                           enableDittoCloudSync:(BOOL)enableDittoCloudSync;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    authenticationDelegate

    a handler for when Ditto requires (re-)authentication.

    enableDittoCloudSync

    if true, auto-configure sync with Ditto Cloud.

    Return Value

    An Online identity suitable for a production Ditto deployment.

  • Deprecated

    use initOnlineWithAuthenticationWithAppID instead.

    Creates an Online identity.

    Online identities should be used when running Ditto in secure production mode, logging on to Ditto Cloud, or using an on-premises authentication server. User permissions are centrally managed. Sync will not work until a successful login has occurred.

    The only required configuration is the application’s UUID, which can be found on the Ditto portal where the app is registered, and an authentication delegate. If you don’t want/need to provide a value for enableDittoCloudSync or customAuthURL then use one of the other initOnline-prefixed methods.

    By default cloud sync is enabled. This means the SDK will sync to a Big Peer in Ditto’s cloud when an internet connection is available. This is controlled by the enableDittoCloudSync parameter. If true (default), a suitable wss:// URL will be added to the TransportConfig. To prevent cloud sync, or to specify your own URL later, pass false.

    Authentication requests are handled by Ditto’s cloud by default, configured in the portal at https://portal.ditto.live.

    To use a different or on-premises authentication service, pass a custom HTTPS base URL as the customAuthURL parameter.

    Declaration

    Objective-C

    - (nonnull instancetype)initOnlineWithAppID:(nonnull NSString *)appID
                         authenticationDelegate:
                             (nonnull id<DITAuthenticationDelegate>)
                                 authenticationDelegate
                           enableDittoCloudSync:(BOOL)enableDittoCloudSync
                                  customAuthURL:(nullable NSURL *)customAuthURL
                           persistenceDirectory:(nullable NSURL *)directory;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    authenticationDelegate

    a handler for when Ditto requires (re-)authentication.

    enableDittoCloudSync

    if true, auto-configure sync with Ditto Cloud.

    customAuthURL

    if specified, use a custom authentication service instead of Ditto Cloud.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    An Online identity suitable for a production Ditto deployment.

  • Creates an OnlineWithAuthentication identity.

    OnlineWithAuthentication identities should be used when running Ditto in secure production mode, logging on to Ditto Cloud, or using an on-premises authentication server. User permissions are centrally managed. Sync will not work until a successful login has occurred.

    The only required configuration is the application’s UUID, which can be found on the Ditto portal where the app is registered, and an authentication callback. If you want to configure a custom auth URL or specify that you don’t want cloud sync to be used then use one of the other initOnlineWithAuthentication-prefixed methods.

    By default cloud sync is enabled. This means the SDK will sync to a Big Peer in Ditto’s cloud when an internet connection is available. This is controlled by the enableDittoCloudSync parameter found in the other initOnlineWithAuthentication-prefixed methods. If true (default), a suitable wss:// URL will be added to the TransportConfig. To prevent cloud sync, or to specify your own URL later, pass false.

    Authentication requests are handled by Ditto’s cloud by default, configured in the portal at https://portal.ditto.live.

    To use a different or on-premises authentication service, use the appropriate initOnlineWithAuthentication-prefixed method and pass a custom HTTPS base URL as the customAuthURL parameter.

    Declaration

    Objective-C

    - (nonnull instancetype)
        initOnlineWithAuthenticationWithAppID:(nonnull NSString *)appID
                       authenticationDelegate:
                           (nonnull id<DITAuthenticationDelegate>)
                               authenticationDelegate;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    authenticationDelegate

    a handler for when Ditto requires (re)authentication.

    Return Value

    An OnlineWithAuthentication identity suitable for a production Ditto deployment.

  • Creates an OnlineWithAuthentication identity.

    OnlineWithAuthentication identities should be used when running Ditto in secure production mode, logging on to Ditto Cloud, or using an on-premises authentication server. User permissions are centrally managed. Sync will not work until a successful login has occurred.

    The only required configuration is the application’s UUID, which can be found on the Ditto portal where the app is registered, and an authentication callback. If you don’t want/need to provide a value for enableDittoCloudSync then use one of the other initOnlineWithAuthentication-prefixed methods.

    By default cloud sync is enabled. This means the SDK will sync to a Big Peer in Ditto’s cloud when an internet connection is available. This is controlled by the enableDittoCloudSync parameter. If true (default), a suitable wss:// URL will be added to the TransportConfig. To prevent cloud sync, or to specify your own URL later, pass false.

    Authentication requests are handled by Ditto’s cloud by default, configured in the portal at https://portal.ditto.live.

    To use a different or on-premises authentication service, pass a custom HTTPS base URL as the customAuthURL parameter.

    Declaration

    Objective-C

    - (nonnull instancetype)
        initOnlineWithAuthenticationWithAppID:(nonnull NSString *)appID
                       authenticationDelegate:
                           (nonnull id<DITAuthenticationDelegate>)
                               authenticationDelegate
                         enableDittoCloudSync:(BOOL)enableDittoCloudSync;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    authenticationDelegate

    a handler for when Ditto requires (re-)authentication.

    enableDittoCloudSync

    if true, auto-configure sync with Ditto Cloud.

    Return Value

    An OnlineWithAuthentication identity suitable for a production Ditto deployment.

  • Creates an OnlineWithAuthentication identity.

    OnlineWithAuthentication identities should be used when running Ditto in secure production mode, logging on to Ditto Cloud, or using an on-premises authentication server. User permissions are centrally managed. Sync will not work until a successful login has occurred.

    The only required configuration is the application’s UUID, which can be found on the Ditto portal where the app is registered, and an authentication delegate. If you don’t want/need to provide a value for enableDittoCloudSync or customAuthURL then use one of the other initOnlineWithAuthentication-prefixed methods.

    By default cloud sync is enabled. This means the SDK will sync to a Big Peer in Ditto’s cloud when an internet connection is available. This is controlled by the enableDittoCloudSync parameter. If true (default), a suitable wss:// URL will be added to the TransportConfig. To prevent cloud sync, or to specify your own URL later, pass false.

    Authentication requests are handled by Ditto’s cloud by default, configured in the portal at https://portal.ditto.live.

    To use a different or on-premises authentication service, pass a custom HTTPS base URL as the customAuthURL parameter.

    Declaration

    Objective-C

    - (nonnull instancetype)
        initOnlineWithAuthenticationWithAppID:(nonnull NSString *)appID
                       authenticationDelegate:
                           (nonnull id<DITAuthenticationDelegate>)
                               authenticationDelegate
                         enableDittoCloudSync:(BOOL)enableDittoCloudSync
                                customAuthURL:(nullable NSURL *)customAuthURL
                         persistenceDirectory:(nullable NSURL *)directory;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    authenticationDelegate

    a handler for when Ditto requires (re-)authentication.

    enableDittoCloudSync

    if true, auto-configure sync with Ditto Cloud.

    customAuthURL

    if specified, use a custom authentication service instead of Ditto Cloud.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    An OnlineWithAuthentication identity suitable for a production Ditto deployment.

  • Creates an OnlinePlayground identity.

    OnlinePlayground identities should be used when you want to test a Ditto Cloud app without authentication (“Playground mode”). This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOnlinePlaygroundWithAppID:(nonnull NSString *)appID;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    Return Value

    An Online identity suitable when using Ditto in development.

  • Creates an OnlinePlayground identity.

    OnlinePlayground identities should be used when you want to test a Ditto Cloud app without authentication (“Playground mode”). This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOnlinePlaygroundWithAppID:(nonnull NSString *)appID
                                     enableDittoCloudSync:
                                         (BOOL)enableDittoCloudSync;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    enableDittoCloudSync

    if true, auto-configure sync with Ditto Cloud.

    Return Value

    An OnlinePlayground identity suitable when using Ditto in development.

  • Creates an OnlinePlayground identity.

    OnlinePlayground identities should be used when you want to test a Ditto Cloud app without authentication (“Playground mode”). This mode offers no security and must only be used for development.

    Declaration

    Objective-C

    - (nonnull instancetype)initOnlinePlaygroundWithAppID:(nonnull NSString *)appID
                                     enableDittoCloudSync:(BOOL)enableDittoCloudSync
                                     persistenceDirectory:
                                         (nullable NSURL *)directory;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    enableDittoCloudSync

    if true, auto-configure sync with Ditto Cloud.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    An OnlinePlayground identity suitable when using Ditto in development.

  • Creates a shared key identity with the provided app ID, site ID and shared key.

    Identities created using this init should be used where any device is trusted provided they know the shared key. This is a simplistic authentication model normally only suitable for private apps where users and devices are both trusted. In this mode, any string may be used as the app ID.

    Declaration

    Objective-C

    - (nonnull instancetype)initSharedKeyWithAppID:(nonnull NSString *)appID
                                         sharedKey:(nonnull NSString *)sharedKey
                                            siteID:(uint64_t)siteID;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    sharedKey

    a base64-encoded DER private key. Refer to Ditto documentation for details about generating shared keys.

    siteID

    the site ID of the peer.

    Return Value

    A shared key identity

  • Creates a shared key identity with the provided app ID, site ID and shared key.

    Identities created using this init should be used where any device is trusted provided they know the shared key. This is a simplistic authentication model normally only suitable for private apps where users and devices are both trusted. In this mode, any string may be used as the app ID.

    Declaration

    Objective-C

    - (nonnull instancetype)initSharedKeyWithAppID:(nonnull NSString *)appID
                                         sharedKey:(nonnull NSString *)sharedKey
                                            siteID:(uint64_t)siteID
                              persistenceDirectory:(nullable NSURL *)directory;

    Parameters

    appID

    a UUID identifying this app registration on the Ditto portal, which can be found at https://portal.ditto.live.

    sharedKey

    a base64-encoded DER private key. Refer to Ditto documentation for details about generating shared keys.

    siteID

    the site ID of the peer.

    directory

    The directory that will be used to persist Ditto data.

    Return Value

    A shared key identity

  • Creates a Manual identity using the provided certificate config.

    Declaration

    Objective-C

    - (nonnull instancetype)initManualWithCertificateConfig:
        (nonnull NSString *)certificateConfig;

    Parameters

    certificateConfig

    a base64 encoded string representation of a certificate bundle.

    Return Value

    A Manual identity using the provided certificate config.