Skip to content

iOS SDK: Migrating from v3 to v4

Version 4.0.0 is a full rewrite of the Castle iOS SDK in Swift, replacing the previous Objective-C implementation. This guide covers all breaking changes and how to update your integration.

Requirements#

  • iOS 13+ v4 drops support for iOS versions below 13.

Breaking changes#

1.Import name#

// v3
import Castle
// v4
import CastleSDK

2.Configuration#

  • Castle.configureAsync is new function, for better async support
  • The Castle.configure and Castle.configureAsync call can now throw CastleConfigurationError exceptions when the publishable key is invalid, configure is not called from the main thread or other settings are invalid.
  • configure (sync version) is required to be called from the main thread, due to internal information collection, UIKit and other internal libraries require, as defined per Apple, to be run from main thread.
// v3
Castle.configure(publishableKey: "{Publishable-API-Key}")

// v4
let configuration = CastleConfiguration(publishableKey: "{Publishable-API-Key}")

// configure is a sync call required to run from main thread
try! Castle.configure(configuration)

// configureAsync is dispatched async to the main thread
do {
    try await Castle.configureAsync(configuration)
    NSLog("Castle configure successful")
    // setup userJWT
    // createRequestToken
} catch {
    NSLog("Castle configure failed: \(error)")
}

3.Request Token Creation#

The createRequestToken method doesn’t accept any options and generates tokens synchronously. Tokens can be created from any thread, they have no main thread requirement due to internal cache and observer architecture. It is strongly advised to not create a token directly after configure , to give the SDK time to collect sensor data.

Furthermore if tokens are requested without the SDK being initialized the returned token will be nil.

// v3
let token: String = Castle.createRequestToken() // "" if not configured

// v4
let token: String? = Castle.createRequestToken() // nil if not configured

Complete Integration Sample#

import CastleSDK

// sync version
let configuration = CastleConfiguration(publishableKey: "{Publishable-API-Key}")
configuration.isDebugLoggingEnabled = true

do {
	try Castle.configure(configuration)
  // Castle is ready - set user identity and track events
  // if available, otherwise set at user login
  Castle.userJwt("user-jwt-token")
  Castle.screen(name: "App Started")
} catch {
  NSLog("Castle configure failed: \(error)")
}

// async version
func setupCastle() async {
    let configuration = CastleConfiguration(publishableKey: "{Publishable-API-Key}")
    configuration.isDebugLoggingEnabled = true

    do {
        try await Castle.configureAsync(configuration)
        // Castle is ready - set user identity and track events
        // if available, otherwise set at user login
        Castle.userJwt("user-jwt-token")
        Castle.screen(name: "App Started")
    } catch {
        print("Castle configuration failed: \(error)")
    }
}

// recommended usage form didFinishLaunching
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    Task.detached {
        await setupCastle()
    }
    return true
}