iOS

Supported platforms

The iOS SDK supports following platforms:

iOS
iPhone
iPad

Requirements

Install or update Xcode to the latest version.
Make sure that your project meets the following requirements:
1. platform should not be below the following versions
- iOS 9
  - macOS 10.12
  - tvOS11
  - watchOS 5
Set up an Apple physical device or use an simulator to run your app.

Getting Started

The following will outline how to get up and running with ABetterChoice for iPhone/iPad.

To work with the SDK, you will need a ABetterChoice project.Create a Project

If you don't yet have a project, you can sign up for a free one here or ask us for help. You could skip this for now.

Installation

Integration via CocoaPods Install the internal local repository (temporarily hosted in the internal repository):

groovy

pod repo add Tencent http://git.woa.com/T-CocoaPods/Specs.git

Add the following code to your project's Podfile:

groovy

.......
source 'http://git.woa.com/T-CocoaPods/Specs.git'
# Integration with source code
pod 'abetterchoice', '1.0.1'
# Binary integration
pod 'abetterchoice', '1.0.1-bin'
......

Note: The SDK depends on MMKV, Protobuf third-party libraries.

Save and execute pod install. Note: If the command-line execution of pod search abetterchoice shows that the version of abetterchoice is not the latest, please first execute a pod repo update operation to update the content of the local repository.

SDK Integration

You want to initialize the SDK after installing. One project ID is required to provide in initialization. We also support providing multiple project ID(s) by multiple SDK objects.

Import the header file in the AppDelegate.m file of your project.

java

.......
import <abetterchoice/AbcExpSDK.h>
.......

If your project is in Swift, please import it in the corresponding bridging-header.h.

Initialize the SDK in the corresponding project file method.

objective-c

........
// Set the log level
[AbcExpSDK setLogLevel:5];
// Configure the function parameters
AbcExpOptions *expOptions = [[AbcExpOptions alloc] init];
expOptions.projectId = PROJECT_ID; // required, sets the business assigned by the platform
expOptions.unitId = UNIT_ID; // required, the unique identifier of the user
expOptions.secretKey = PROJECT_TOKEN; // required, used for business authentication
expOptions.autoPoll = YES; // optional, defaults to true. When set to false, data will not be updated by polling in the SDK
expOptions.profiles = [self generateAttributes]; //optional, can be used for label experiments

// Create an instance of SDK
AbcExpSDK *defaultSDK = [AbcExpSDK createSDKWithOptions:expOptions];
......

Create a new experiment You can follow the guide documentation to create a new experiment to introduce into the SDK code. Tutorial documentation URL: https://iwiki.woa.com/pages/viewpage.action?pageId=4006870035.
Launch SDK function

objective-c

.......
// After creating an instance of SDK, get the business ID configured during the initialization of SDK to obtain the instance of SDK
AbcExpSDK *defaultSDK = [AbcExpSDK abcSDK:project_id];

// Required to start the use of the SDK. The SDK will pull the experiment data information under the current project ID and make relevant pre-initialized status treatment. The method parameters refer to the internal state of the SDK
[defaultSDK start:^(BOOL result) {
  dispatch_async(dispatch_get_main_queue(), ^{
    if (result) {
      NSLog(@"Business: SDK started successfully!");
    }
  });
}];

.......
// After, call different interfaces according to the SDK object of the function interface

Call the functional interface

objective-c

/-————————————————————————Getting Experiment Information————————————————————————————————/
// Get experiment information interface, other information acquisition interfaces can check ITabExpData interface file

// Get experiment traffic hitting information
AbcExpInfo *expInfo = [defaultSDK getExperiment: @"test_exp_layer"];
if (!expInfo) {
  // Indicates hitting the default version, data abnormality, or experiment shutdown
  handleView("Default version"); // Execute the default version
  return;
}

// Get the experiment parameters that are hit
NSString *paramValue = [expInfo stringValue:@"paramKey" defVal:@"defVal"];
// Execute different business logics according to the configuration parameter values of the experiments hit
if ([parmValue isEqualToString:@"Experiment Group Version Configuration Parameter Value"]) {
  NSLog(@"Experiment group"); // Execute the related logic of the experiment group
} else if ([parmValue isEqualToString:@"Control Group Version Configuration Parameter Value"]) {
  NSLog(@"Control Group"); // Execute the related logic of the control group
} else {
  NSLog(@"Other Version"); // Execute other version name logic
}

/-————————————————————————Account switching————————————————————————————————/
// Switch accounts, "otherUnitId" represents other flow accounts
[defaultSDK switchUnitId:@"otherUnitId" completeHandler:^(BOOL result）{
  dispatch_async(dispatch_get_main_queue(), ^{
    if (result) {
      NSLog(@"Business: Successfully switched flow accounts in the SDK!");
    }
  });
}];

/-———————————————————-------—————Forced refresh——————————————————————--——————————/
// Will force a data update to the backend, which will increase the cost. Please avoid using it if not necessary.
[abcSdk refreshExperiment:^(BOOL result) {
  dispatch_async(dispatch_get_main_queue(), ^{
    if (result) {
      NSLog(@"Business: The SDK successfully refreshed the traffic data!");
    }
  });
}];

/-———————————————————-------—————Experiment exposure reporting———————————————————--/
// You can choose to manually expose at the appropriate scene.
[abcSdk logExperimentExposure:expInfo];

Getting experiments and logging Exposures

To get experiment traffic splitting configuration information including which group that a unit is assigned to by SDK. This requires users to create an experiment on the web UI first. The response contains detailed information of the group assigned to, including group parameters, which can be fetched by strong type API.

Terms	Meaning
project_id	The abetterchoice business platform assigned by the platform.
unit_id	A unitID can be a userID, a sessionID or a machineID. the SDK assigns a unitID to the same group consistantly.
abcExpInfo	An AB test.
group	There are two or more groups in an experiment, including one control and one or more treatments.

1. New Experiment creation

If you haven't done so, please go to the console and create a new experiment following our doc on how to create an experiment.

2. Fetching experiment assignments

Suppose in step 1 under the project project_id we already created a experiment whose layer name is abc_layer_name, under this layer there is a parameter whose name is should_show_banner and type is Boolean. Note that if you use our basic version the layer name is same with experiment name by default, but if you create new experiments under the same layer you need to find the layer name under the experiment page.

Right now we provide three ways of fetching the traffic assignement given a particular unit id. All the these APIs requires you to get the experiment interface object.

objective-c

AbcExpSDK *defaultSDK = [AbcExpSDK abcSDK: project_id];

a. Fetch experiment by layer key

The first way is getting the experiment assignment by the layer key, and fetching the parameters under the layer via the strong type APIs. This is convenient when you have more than one parameters under the layer/experiment, and this same API will automatically give you the correct result when there are multiple experiments under the same layer, since the unit will and can only fall into one of them. One more benefit of doing this is you can iterate the experiments quickly, by deallocating the old experiment and creating new ones under the same layer without modifying the code.

objective-c

AbcExpInfo *expInfo = [defaultSDK getExperiment: @"abc_layer_name"];
NSString *paramBooleanValue = [expInfo getBoolenValue:@"should_show_banner" defVal:@"true"]; // Boolean

b. Fetch experiment by parameter key

java

AbcExpInfo *expInfo = [defaultSDK getExperiment: @"abc_layer_name"];
NSString *paramBooleanValue = [expInfo getStringValue:@"paramKey" defVal:@"defVal"];

3. Exposure Data Logging

When fetching the experiment assignments above, you can choose to disable exposure logging to prevent exposure dilution, you can log the exposure manually later at the right place:

objective-c

[abcSdk logExperimentExposure:expInfo];

4. Account switching

Switch accounts, "otherUnitID" represents other accounts

java

[defaultSDK switchUnitId:@"otherUnitId" completeHandler:^(BOOL result）{
    dispatch_async(dispatch_get_main_queue(), ^{
        if (result) {
            NSLog(@"Business：SDK successfully switched！");
        }
    });
}];

5. Force Data refresh

Will force to initiate data update to the background

java

[abcSdk refreshExperiment:^(BOOL result) {
  dispatch_async(dispatch_get_main_queue(), ^{
    if (result) {
      NSLog(@"Business: The SDK successfully refreshed the traffic data!");
    }
  });
}];

Example

initialize the SDK

java

........
// Set the log level
[AbcExpSDK setLogLevel:5];
// Configure the function parameters
AbcExpOptions *expOptions = [[AbcExpOptions alloc] init];
expOptions.projectId = project_id; // required, sets the business assigned by the platform
expOptions.unitId = unit_id; // required, the unique identifier of the user
expOptions.secretKey = secretKey; // required, used for business authentication
expOptions.autoPoll = YES; // optional, defaults to true. When set to false, data will not be updated by polling in the SDK
expOptions.profiles = [self generateAttributes]; //optional, can be used for label experiments

// Create an instance of SDK
AbcExpSDK *defaultSDK = [AbcExpSDK createSDKWithOptions:expOptions];
......

use the SDK

java

......
// After creating an instance of SDK, get the business ID configured during the initialization of SDK to obtain the instance of SDK
AbcExpSDK *defaultSDK = [AbcExpSDK abcSDK:project_id];

// Required to start the use of the SDK. The SDK will pull the experiment data information under the current project ID and make relevant pre-initialized status treatment. The method parameters refer to the internal state of the SDK
[defaultSDK start:^(BOOL result) {
  dispatch_async(dispatch_get_main_queue(), ^{
    if (result) {
      NSLog(@"Business: SDK started successfully!");
    }
  });
}];

AbcExpInfo *expInfo = [defaultSDK getExperiment: @"abc_layer_name"];
NSString *paramBooleanValue = [expInfo getBoolenValue:@"should_show_banner" defVal:@"true"];

[abcSdk logExperimentExposure:expInfo];
......

iOS ​

Supported platforms ​

Requirements ​

Getting Started ​

Installation ​

SDK Integration ​

Getting experiments and logging Exposures ​

1. New Experiment creation ​

2. Fetching experiment assignments ​

a. Fetch experiment by layer key ​

b. Fetch experiment by parameter key ​

3. Exposure Data Logging ​

4. Account switching ​

5. Force Data refresh ​

Example ​

iOS

Supported platforms

Requirements

Getting Started

Installation

SDK Integration

Getting experiments and logging Exposures

1. New Experiment creation

2. Fetching experiment assignments

a. Fetch experiment by layer key

b. Fetch experiment by parameter key

3. Exposure Data Logging

4. Account switching

5. Force Data refresh

Example