Skip to main content

iOS reference

This category contains topics explaining how to configure Bucketeer's iOS SDK.

Compatibility

The Bucketeer iOS SDK is compatible with iOS versions 10.0 and higher.

Getting started

Before starting, ensure that you follow the Getting started guide.

Implementing dependency

Implement the dependency in your Podfile file. Please refer to the SDK releases page to find the latest version.

use_frameworks!target 'YOUR_TARGET_NAME' do  pod 'Bucketeer', 'LATEST_VERSION'end

Importing client

Import the Bucketeer client into your application code.

import Bucketeer

Configuring client

Configure the SDK config and user configuration.

let config = BKTConfig(  apiKey: "YOUR_API_KEY",  apiURL: "YOUR_API_URL",  featureTag: "YOUR_FEATURE_TAG")let user = BKTUser(id: "USER_ID")
Custom configuration

Depending on your use, you may want to change the optional configurations available in the BKTConfig.

  • pollingInterval (Minimum 5 minutes. Default is 10 minutes)
  • backgroundPollingInterval (Minimum 20 minutes. Default is 1 hour)
  • eventsFlushInterval (Default is 30 seconds)
  • eventsMaxQueueSize (Default is 50 events)
note

The Bucketeer SDK doesn't save the user data. The Application must save and set it when initializing the client SDK.

Initializing client

Initialize the client by passing the configurations in the previous step.

BKTClient.initialize(config: config, user: user)

:::

note

The initialize process starts polling the latest variations from Bucketeer in the background using the interval pollingInterval configuration. When your application moves to the background state, it will use the backgroundPollingInterval configuration.

If you want to use the feature flag on Splash or Main views, and the user opens your application for the first time, it may not have enough time to fetch the variations from the Bucketeer server.

For this case, we recommend using the callback in the initialize method.

// The callback will return without waiting until the fetching variation process finisheslet timeout = 1000 // Default is 5 secondsBKTClient.initialize(config: config, user: user, completion: { (result) -> () in  let client = BKTClient.get()!  guard case .success = result else {    // The code to run when the feature is off    return  }  let showNewFeature = client.boolVariation(featureID: "YOUR_FEATURE_FLAG_ID", defaultValue: false)  if (showNewFeature) {      // The Application code to show the new feature  } else {      // The code to run when the feature is off  }}, timeout: timeout)

Supported features

Evaluating user

The variation method determines whether or not a feature flag is enabled for a specific user.
To check which variation a specific user will receive, you can use the client like below.

let client = BKTClient.get()!let showNewFeature = client.boolVariation(featureID: "YOUR_FEATURE_FLAG_ID", defaultValue: false)if (showNewFeature) {    // The Application code to show the new feature} else {    // The code to run when the feature is off}
note

The variation method will return the default value if the feature flag is missing in the SDK.

Variation types

The Bucketeer SDK supports the following variation types.

func boolVariation(featureId: String, defaultValue: Bool) -> Boolfunc stringVariation(featureId: String, defaultValue: String) -> Stringfunc intVariation(featureId: String, defaultValue: Int) -> Intfunc doubleVariation(featureId: String, defaultValue: Double) -> Doublefunc jsonVariation(featureId: String, defaultValue: Any?) -> Any?

Updating user variations

Sometimes depending on your use, you may need to ensure the variations in the SDK are up to date before evaluating a user.

The fetch method uses the following parameters.

  • Callback
  • Timeout (The callback will return without waiting until the fetching variation process finishes. The default is 5 seconds)
// The callback will return without waiting until the fetching variation process finisheslet timeout = 1000 // Default is 5 secondslet client = BKTClient.get()!client.fetchEvaluations(completion: { (result) -> () in  guard case .success = result else {    // The code to run when the feature is off    return  }  let showNewFeature = client.boolVariation(featureID: "YOUR_FEATURE_FLAG_ID", defaultValue: false)  if (showNewFeature) {      // The Application code to show the new feature  } else {      // The code to run when the feature is off  }}, timeout: timeout)
caution

Depending on the client network, it could take a few seconds until the SDK fetches the data from the server, so use this carefully.

You don't need to call this method manually in regular use because the SDK is polling the latest variations in the background.

Updating user variations in real-time

The Bucketeer SDK supports FCM (Firebase Cloud Messaging). Every time you change some feature flag, Bucketeer will send notifications using the FCM API to notify the client so that you can update the variations in real-time.

Assuming you already have the FCM implementation in your application.

// TODO
note

1- You need to register your FCM API Key on the console UI. See more.

2- This feature may not work if the user has the notification disabled.

Reporting custom events

This method lets you save user actions in your application as events. You can connect these events to metrics in the experiments console UI.

In addition, you can pass a double value to the goal event. These values will sum and show as
Value total on the experiments console UI. This is useful if you have a goal event for tracking how much a user spent on your application buying items, etc.

client.track("YOUR_GOAL_ID", 10.50)

Flushing events

This method will send all pending analytics events to the Bucketeer server as soon as possible. This process is asynchronous, so it returns before it is complete.

client.flush()
note

In regular use, you don't need to call the flush method because the events are sent every 30 seconds in the background.

User attributes configuration

This feature will give you robust and granular control over what users can see on your application. You can add rules using these attributes on the console UI's feature flag's targeting tab. See more.

let attributes = [  "app_version": "1.0.0",  "os_version": "11.0.0",  "device_model": "pixel-5"  "language": "english",  "genre": "female",]let user = BKTUser(id: "USER_ID", attributes)BKTClient.initialize(config: config, user: user)

Updating user attributes

This method will update all the current user attributes. This is useful in case the user attributes update dynamically on the application after initializing the SDK.

let attributes = [  "app_version": "1.0.1",  "os_version": "11.0.0",  "device_model": "pixel-5"  "language": "english",  "genre": "female",  "country": "japan",]client.updateUserAttributes(attributes)
caution

This updating method will override the current data.

Getting user information

This method will return the current user configured in the SDK. This is useful when you want to check the current user id and attributes before updating them through updateUserAttributes.

let user = client.currentUser()

Getting evaluation details

This method will return the evaluation details for a specific feature flag. This is useful if you need to know the variation reason or send this data elsewhere.

let evaluationDetails = client.evaluationDetails("YOUR_FEATURE_FLAG_ID")
note

This method will return nil if the feature flag is missing in the SDK.