4.2. iOS SDK 集成文档

优质

小牛编辑

154浏览

2023-12-01

iOS SDK 集成文档

iOS SDK API 参考

下载SDK

AppAdhoc iOS SDK

导入SDK

使用CocoaPods安装，只需在项目根目录的Podfile文件中添加：

pod 'AdhocSDK', '~> 5.2.6'

或者精简包：（不可同时pod两个包）

pod 'AdhocSDKLite', '~> 5.2.6'

然后在Terminal中执行：

pod install

您也可以使用手工导入的方式

Objective-C | Swift

将下载得到的 AdhocSDK.framework 拖入到的Xcode工程目录Supporting Files中，在弹出的options界面中勾选 Copy items if needed，并确保 Add to targets 勾选相应的 target：

检查 TARGETS --> Build Phases --> Link Binary With Libraries 选项下是否已经加入 Security.framework，CFNetwork.framework，CoreTelephony.framework，AdSupport.framework，SystemConfiguration.framework ，AVFoundation.framework，AdhocSDK.framework，如果没有，请手动加入。并手动链接libsqlite3.tbd和libicucore.tbd：

在 TARGETS --> Build Settings 选项下 Other Linker Flags 中设置链接器参数： -ObjC。

新建"Bridging-Header.h"文件，并在该文件中引入AdhocSDK头文件@import AdhocSDK，在 TARGETS —> Build Settings 选项下 Objective-C Bridging Header 写入"Bridging-Header.h"文件的相对路径。

权限设置

1.在info.plist文件中添加相机权限：

2.为了保证用户的唯一性，SDK将设备ID存储在本地Keychain中，iOS10需在Capabilities中打开Keychain sharing

3.如果您的应⽤本身已经集成了广告服务，可直接使⽤我们的SDK产品。如果您的应用未集成任何⼴告服务，在集成我们的SDK后，提交AppStore审核时可能出现失败的情况。您可参照以下内容的介绍来解决。

应⽤在提交AppStore审核时，关于IDFA的选项说明如下 (请按项目需要进⾏勾选，如果原先无配置默认勾选第二个和第四个框):

idfa

关于选项的说明及使⽤我们定位SDK时的勾选建议:

在APP内投放广告: 服务应用中的广告。如果您的应用集成了广告服务，请勾选此项;
将此APP安装归因于先前投放的特定广告: 跟踪广告带来的安装。如果您的应用没有集成任何广告服务，请勾选此项;
将此APP中发⽣的操作归因于先前投放的特定⼴告: 跟踪广告带来的用户的后续行为。如果您的应用集成了广告服务，并且需要跟踪用户的后续行为，请勾选此项;
iOS中的“限制⼴告跟踪”设置: 这⼀项的内容其实就是对您的应⽤使⽤IDFA的目的做下确认，只要您选择了采集IDFA，那么这一项都是需要勾选的。

SDK初始化

在调用SDK之前，记得在AppDelegate.m中引用头文件：

#import "AdhocSDK/AdhocSDK.h"

在@selector(application:didFinishLaunchingWithOptions:)中：

Objective-C | Swift

AdhocSDKConfig *config = [AdhocSDKConfig defaultConfig];
//平台获得的appKey必要
config.appKey = @"ADHOC_5dc7130b-27ad-444e-xxxxxxxxxxxxxxxx";
//debug悬浮窗开关
config.enableDebugAssist = YES;
//开启实时上报
//config.reportImmediatelyEnabled = YES;
[AdhocSDK startWithConfigure:config options:launchOptions];

var config:AdhocSDKConfig = AdhocSDKConfig.defaultConfig() as! AdhocSDKConfig
config.appKey = “ADHOC_xxx”
AdhocSDK.start(withConfigure: config, options: launchOptions)

并设置appKey为 AppAdhoc 后台的app_key值。“app_key” 是在登录 AppAdhoc 后,创建“应用”之后获得的授权标识。

可在AppAdhoc控制台应用列表找到，如下图红线部分：

app_key

注:请不要延迟SDK的初始化，会导致无法监听到AppDelegate里的方法，无法加载Flags信息，可视化试验无法正常渲染。

请勿在SDK基础上进行自行封装，以免影响到试验逻辑，造成试验无法正常运行。

编程模式：根据“试验变量”展示相应内容

在编程模式中，“试验变量”的值决定了展示的内容或程序的逻辑。可视化试验可跳过此步骤。

注意：试验变量值应由PM或相关A/B Testing需求制定人员在后台提前录入完毕，如下图“版本管理”红线部分：

app_key

在调用SDK之前，记得引用头文件：

#import "AdhocSDK/AdhocSDK.h"

根据所获取的试验变量设置来执行不同版本的代码，在相应的测试页面添加代码.

方法一：getFlag方法，该方法只取本地缓数据，默认一个小时从服务器获取一次试验数据。

Objective-C | Swift


- (void)viewWillAppear:(BOOL)animated {
  [super viewWillAppear:animated];
  //获取系统生成的试验变量isNewHomePage的值
  NSInteger value = [[AdhocSDK getFlag:@"isNewHomePage" default:@(0)] integerValue];
  switch (value) {
    case 0:
      // 执行默认版本或原始版本逻辑
      break;
    case 1:
      // 执行版本1逻辑
      break;
    case 2:
      // 执行版本2逻辑
      break;
    }
}

override func viewWillAppear(animated: Bool) {
      super.viewWillAppear(animated)
      //获取试验变量isNewHomePage的值
      let value: Int = AdhocSDK.getFlag("isNewHomePage", default: 0) as! Int;
          switch value {
          case 0:
              print("执行默认版本或原始版本逻辑")
          case 1:
              print("执行版本一逻辑")
          case 2:
              print("执行版本二逻辑")
          default:
              print("执行默认版本或原始版本逻辑")
          }
}

方法二：asyncGetFlag方法，从网络获取变量，并执行回调，每次调用都会从服务器获取试验数据。

/**
* 异步⽅方式从服务器器直接获取试验变量量的值 *
* @param flagName adhoc后台设置的试验变量量名字
* @param defaultValue 指定试验变量量的默认值
* @param timeoutInterval 设置此次⽹网络请求的超时时间，单位为秒(s)，默认 30s
* @param completionHandler ⽹网络执⾏行行结束后的相关操作 */
+ (void)asynchronousGetFlag:(NSString *)flagName
               defaultValue:(id)defaultValue
            timeoutInterval:(NSTimeInterval)timeoutInterval
          completionHandler:(void (^)(id flagValue, NSError *error))completionHandler;

具体调用：

Objective-C | Swift


[AdhocSDK asynchronousGetFlag:@"试验变量量名称" defaultValue:@"试验变量量默认值" timeoutInt erval:30 completionHandler:^(id flagValue, NSError *error) {
   NSLog(@"flagValue = %@", flagValue);
}];


AdhocSDK.asynchronousGetFlag("试验变量量名称", defaultValue: "试验变量量默认值", timeoutInt erval: 30) {
  (flagValue, error) in print("flagValue = \(String(describing: flagValue))")
}

其中，'isNewHomePage' 即是“试验变量“，应与上图中红线标识保持一致。

请注意在用户访问到试验页面时，需要触发试验变量才算作进入该试验，否则将不会统计进入该试验。在此示例中，“AdhocSDK getFlag:@"isNewHomePage" default:@(0)”算作触发变量“isNewHomePage”。

编程模式：上报指标

指标用于量化试验结果的好坏，AppAdhoc 后台中的试验图表根据此数据生成。

优化指标

比如在进入某一逻辑分支后，可以统计点击次数。将上图中的指标“clickTimes”传入函数track实现上报指标, 每次累加1：

Objective-C | Swift

[AdhocSDK track:@"clickTimes" value:@(1)];

如果希望对某一指标统计但同时又希望对该指标统计一次，类似对某一帖子打开统计，打开多次只统计一次，可以使用distinctTrack方法。参数“clickTimes”是指标名称，“1”是统计数值，第三个参数“id123456”是一个类似唯一id的值，由开发者传入，比如该值可以是某帖子详情的id，该方法可以实现用户设备最多上报一次。

[AdhocSDK distinctTrack:@"clickTimes" value:@(1) tag:@"id123456"];  // 通过tag"id123456"去重

AdhocSDK.track("clickTimes", value: 1)

AdhocSDK.distinctTrack("clickTimes", value: 1, tag: "id123456")  // 通过tag"id123456"去重

可视化模式

可视化轮播图使用说明

UIView（Adhoc）分类添加一个属性 adhoc_idf（此属性必须是数字字符串如cell.adhoc_idf = @"1"）
SDK会自动检索当前view是否存在此属性,存在则找到对应view进行属性修改
示例
这个属性 adhoc_idf 用来标识当前轮播的index

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath
{
    SDCollectionViewCell *cell = [collectionView dequeueReusableCellWithReuseIdentifier:ID forIndexPath:indexPath];
    long itemIndex = indexPath.item % self.imagePathsGroup.count;
    //可视化编辑轮播图调用
    cell.adhoc_idf = [NSString stringWithFormat:@"%ld",itemIndex];

    NSString *imagePath = self.imagePathsGroup[itemIndex];

    ...

    return cell;
}

可视化UITableView的使用说明

iOS 可视化编辑务必保障下图中这个方法有调用到indexpath这个参数，如果未使用indexPath，则cell无法绑定行号(对应编号的cell)，无法保障可视化编辑列表控件可以正常编辑。

 UITableViewCell *cell = [self.tableView dequeueReusableCellWithIdentifier:identifier forIndexPath:indexPath];

可视化UILabel和UITextField的按钮使用说明

使用可视化编辑器修改文字大小，建议在控件大小范围内，如果超出控件大小文字会显示异常

可视化编辑GIF图的使用说明

如需编辑GIF图，请联系我们的技术支持

集成调试

集成调试只是为验证SDK的集成是否成功（并不是真正开始试验！）。

Objective-C | Swift

在SDK启动时设置是否显示调试按钮

AdhocSDKConfig *config = [AdhocSDKConfig defaultConfig];
#ifdef DEBUG
    config.enableDebugAssist = YES;
#else
    config.enableDebugAssist = NO;
#endif
[AdhocSDK startWithConfigure:config options:launchOptions];

在工程任意地方添加如下代码:

var config:AdhocSDKConfig = AdhocSDKConfig.defaultConfig() as! AdhocSDKConfig
#if DEBUG
    config.enableDebugAssist = true
#else
    config.enableDebugAssist = false
#endif
AdhocSDK.start(withConfigure: config, options: launchOptions)

在Debug模式下启动APP，会出现下图中的悬浮图标：详细使用请参考iOS集成调试。

在debug模式下启动APP的悬浮图标

点击上面的悬浮图标，扫描后台系统“集成调试”中的二维码，进入相应试验：

app_key

开始试验

恭喜，您完成了AppAdhoc AB Testing SDK的埋点集成工作，请通知PM或相关AB Test需求制定人员，点下开始试验按钮吧！

注意：确保app_key, 试验变量字符串，指标字符串与后台截图处一一对应，否则可能出现异常或无试验数据情况。

高级功能受众定向（需要联系管理员开启）

AppAdhoc SDK 支持预定义受众定向和自定义受众定向两种方式。

预定义受众定向功能中，开发者只需要在AppAdhoc平台中选择预设的受众标签，SDK会自动采集相关信息并判定当前用户是否进入试验（例如APP版本、语言等用户标签），无需在代码中定义。

开发者也可以根据需要选择自定义手中标签，此方式需要在AppAdhoc平台中填写好标签的key和value，之后再代码中为当前用户设置标签，进而实现将不符合条件的用户排除在此次试验之外。比如只想要女性用户，或30岁以下的用户参与试验等。

关于受众定向详细请参考受众定向。

注意：自定义受众定向条件应由PM或相关AB Test需求制定人员在后台提前录入完毕，如下图“受众定向”红线部分。

在运行控制/右侧定向试验：

受众定向

选择分组，点击编辑用户群：

受众定向

即得到受众条件的key，在下图例子中，“sex”是key：

受众定向

自定义受众定向：

移动端代码中通过“custom”添加自定义标签名及标签值，这里需要动态获取标签值上传给后台，以便后台决定该用户是否满足受众定向条件(如有疑问请联系客户经理协助)

AdhocSDKConfig *config = [AdhocSDKConfig defaultConfig];
// 平台获得的 App Key(必填)
config.appKey = @"Your appKey";
// 创建定向标签
NSString *gender = @"Male";
// 设置定向条件
[config addCustomAttribute:gender forKey:@"gender"];
[AdhocSDK startWithConfigure:config options:launchOptions];

“app_key” 是在登录 AppAdhoc 后台创建“应用”之后获得的该“应用”的授权标识。

可在AppAdhoc控制台应用列表找到，如下图红线部分：

受众定向

API 参考

iOS SDK API 参考

4.2. iOS SDK 集成文档

iOS SDK 集成文档

下载SDK

导入SDK

权限设置

SDK初始化

编程模式：根据“试验变量”展示相应内容

编程模式：上报指标

可视化模式

可视化轮播图使用说明

示例

可视化UITableView的使用说明

可视化UILabel和UITextField的按钮使用说明

可视化编辑GIF图的使用说明

集成调试

开始试验

高级功能 受众定向（需要联系管理员开启）

高级功能受众定向（需要联系管理员开启）