iOS SDK 集成指南

集成引言

在集成openinstall SDK之前,请您仔细阅读本引言内容。引言内容对您的App上架AppStore参数还原精度等众多方面有很大的帮助!
1、为了保证您这边的App能正常上架AppStore,请在App的《隐私政策》中加入openinstall SDK需要获取的数据、用途以及使用范围,详细内容可以参考官网文档中的《合规指南》。确保用户同意App的《隐私政策》之后,再进行openinstall SDK初始化;如果用户不同意,则不进行openinstall SDK初始化。
2、因为iOS系统的网络权限需要用户手动确认授权的原因,以及首次安装App需点击《隐私政策》弹窗后再调用的SDK初始化方法,建议开发者将获取参数接口(getInstallParmsCompleted)调用时机放到App业务场景进行中时(保证网络畅通时),避免过早的调用。或者使用自定义超时时长的接口(getInstallParmsWithTimeoutInterval),可设置30s以上或更久,避免用户因为网络权限未授权或授权过慢导致参数还原受影响。
3、请在调用初始化接口后再调用其他接口,否则会导致早于初始化接口调用的接口执行失败或者超时。
4、openinstall SDK不影响苹果开发证书,也不会导致苹果开发证书失效,请放心使用。

一、导入 SDK

1. CocoaPods导入

1、cd到项目根目录,执行pod setup
2、在 Podfile 文件中添加命令:pod 'libOpenInstallSDK'

备注:建议先pod repo updatepod update来升级本机 pod 库,然后pod 'libOpenInstallSDK'来获取sdk最新版本。
如果还搜索不到libOpenInstallSDK,则需要同步一下索引,请按下面操作:
1)、先执行:pod setup
2)、再清空搜索索引,让pod重建索引(可能需要等待一会):
rm ~/Library/Caches/CocoaPods/search_index.json

CocoaPods上libOpenInstallSDK版本可能会比原始SDK高,以CocoaPods官网最新数据为准CocoaPods官网

2. 手动导入

下载中心下载 iOS 最新版本 SDK
解压 SDK 压缩包,将文件夹导入工程中(导入请选中 "Copy items if needed" )

二、初始化

Info.plist文件中配置appKey键值对,如下:

<key>com.openinstall.APP_KEY</key>
<string>openinstall 分配给应用的 appkey</string>

AppDelegate中,增加头文件的引用:

//swift开发时,请使用桥接方式引入
#import "OpenInstallSDK.h"

AppDelegate中遵守OpenInstallDelegate协议,参考如下:

Object-C
Swift
@interface AppDelegate ()<OpenInstallDelegate>
@end
class AppDelegate: UIResponder, UIApplicationDelegate, OpenInstallDelegate {
}

application: didFinishLaunchingWithOptions方法中调用initWithDelegate方法来初始化 SDK,如下代码所示:

注意:如果使用了广告平台统计功能,相关的权限申请需要在applicationDidBecomeActive的时候执行,避免系统权限弹窗无法正常弹出的情况发生,参考《指引》

Object-C
Swift
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [OpenInstallSDK initWithDelegate:self];
    return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    //请根据系统代码提示来写
    OpenInstallSDK.initWith(self);
    //例如,有的旧版swift中的写法是OpenInstallSDK.initWithDelegate(self);
    return true;
}

三、功能集成

1. 快速安装

如果只需要快速安装功能,无需其它功能(App传参安装、渠道统计、一键拉起),完成初始化即可

2. 一键拉起

openinstall 通过标准的 Scheme(iOS<9),Universal Links(iOS≥9)技术,在 app 已安装的情况下,从各种浏览器(包括微信、QQ、新浪微博、钉钉等主流社交软件的内置浏览器)拉起 App 并传递动态参数。

2.1 集成通用链接(Universal Links),只适用于iOS9以上
2.1.1 到苹果开发者网站,为当前的 AppID 开启关联域名(Associated Domains)服务:

associatedDev

2.1.2 在 Xcode 中配置 openinstall 为当前应用生成的关联域名(Associated Domains):

添加associatedDomains

2.1.3 在AppDelegate中添加通用链接(Universal Links)回调方法,委托给 openinstall 来处理

Object-C
Swift
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler{
    //处理通过openinstall一键唤起App时传递的数据
    [OpenInstallSDK continueUserActivity:userActivity];
    //其他第三方回调;
     return YES;
}
//swift引用OC方法时,最好根据系统代码提示来写
//注意,swift4.2版本开始,系统方法修改为:
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool{
    OpenInstallSDK.continue(userActivity)
    //其他第三方回调:
    return true
}

2.1.4 如果适配了SceneDelegate的App,需要额外添加以下代码(未使用SceneDelegate可忽略):

Object-C
Swift
//sceneDelegate.m中
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions  API_AVAILABLE(ios(13.0)){
    //最好先加载完UI代码[self.window makeKeyAndVisible];
    //通用链接相关代码,用于App被杀死后一键拉起后传递动态参数
    for (NSUserActivity *userActivity in connectionOptions.userActivities) {
        [OpenInstallSDK continueUserActivity:userActivity];
    }
}
//通用链接相关代码,用于App退到后台时一键拉起后传递动态参数
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity API_AVAILABLE(ios(13.0)){
    [OpenInstallSDK continueUserActivity:userActivity];
}
//sceneDelegate.swift中
@available(iOS 13.0, *)
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        //通用链接相关代码,用于App被杀死后一键拉起后传递动态参数
        for userActivity in connectionOptions.userActivities {
            OpenInstallSDK.continue(userActivity)
        }
   }
//通用链接相关代码,用于App退到后台时一键拉起后传递动态参数
@available(iOS 13.0, *)
    func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
        OpenInstallSDK.continue(userActivity)
    }

备注:关于可能导致的终端用户密码自动存储在openinstall域名下的文档说明:iOS密码钥匙串存储处理指南

2.2 集成 Scheme,只适用于iOS9以下
2.2.1 在Xcode里选中 Target -> Info -> URL Types,配置 openinstall 为当前应用生成的 Scheme,如图所示:

2.2.2 在AppDelegate中添加 Scheme 回调方法,委托给OpeninstallSDK 来处理

注意:当需要在openURL这个方法中处理第三方回调的时候(比如支付宝回调,微信回调等),请注意区分

Object-C
Swift
//适用目前所有iOS版本
-(BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation{
    //处理通过openInstall URL Scheme唤起App的数据
    [OpenInstallSDK handLinkURL:url];
    //其他第三方回调;
    return YES;
}
//iOS9以上,会优先走这个方法
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(nonnull NSDictionary *)options{
    //处理通过openInstall URL Scheme唤起App的数据
    [OpenInstallSDK handLinkURL:url];
    //其他第三方回调;
     return YES;
}
//swift引用OC方法时,最好根据系统代码提示来写
//适用目前所有iOS版本
    func application(_ application: UIApplication, handleOpen url: URL) -> Bool {
        OpenInstallSDK.handLinkURL(url)
        return true
    }
//iOS9以上,会优先走这个方法
//注意,swift4.2版本开始,系统方法修改为:
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool{
        OpenInstallSDK.handLinkURL(url)
        return true
    }

2.2.3 如果适配了SceneDelegate的App,需要额外添加以下代码(未使用SceneDelegate可忽略):

Object-C
Swift
//sceneDelegate.m中
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions  API_AVAILABLE(ios(13.0)){
    //最好先加载完UI代码[self.window makeKeyAndVisible];
    //scheme相关代码
    for (UIOpenURLContext *urlcontext in connectionOptions.URLContexts) {
        [OpenInstallSDK handLinkURL:urlcontext.URL];
    }
}
//scheme相关代码
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts API_AVAILABLE(ios(13.0)){
    for (UIOpenURLContext *urlcontext in URLContexts){
        [OpenInstallSDK handLinkURL:urlcontext.URL];
    }
}
//sceneDelegate.swift中
@available(iOS 13.0, *)
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
	//scheme相关代码
        for urlContext in connectionOptions.urlContexts {
            OpenInstallSDK.handLinkURL(urlContext.url)
        }
   }
//scheme相关代码
@available(iOS 13.0, *)
    func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
        for urlcontext in URLContexts{
            OpenInstallSDK.handLinkURL(urlcontext.url)
        }
    }

2.3 添加拉起参数回调方法

AppDeletegate中遵守协议,添加一键拉起的回调,获取来自 H5 页面的动态参数,根据参数值直达具体页

Object-C
Swift
//通过openInstall获取已经安装App被唤醒时的参数(如果是通过渠道页面唤醒App时,会返回渠道编号)
-(void)getWakeUpParams:(OpeninstallData *)appData{
    if (appData.data) {//(动态唤醒参数)
        //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
    }
    if (appData.channelCode) {//(通过渠道链接或二维码唤醒会返回渠道编号)
        //e.g.可自己统计渠道相关数据等
    }
    NSLog(@"OpenInstallSDK:\n动态参数:%@;\n渠道编号:%@",appData.data,appData.channelCode);
}
//swift引用OC方法时,最好根据系统代码提示来写
//通过openInstall获取已经安装App被唤醒时的参数(如果是通过渠道页面唤醒App时,会返回渠道编号)
    func getWakeUpParams(_ appData: OpeninstallData?) {
        if appData?.data != nil {
            //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
        }
        if appData?.channelCode != nil{
            //e.g.可自己统计渠道相关数据等
        }
        print("唤醒参数 data = \(String(describing: appData?.data)),channelCode = \(String(describing: appData?.channelCode))")
    }

3. App传参安装高级版功能

在 APP 需要安装参数时(由 web 网页中传递过来的,如邀请码、游戏房间号等动态参数),调用getInstallParmsCompleted方法,在回调中获取参数(可重复获取)

Object-C
Swift
[[OpenInstallSDK defaultManager] getInstallParmsCompleted:^(OpeninstallData*_Nullable appData) {
    //在主线程中回调
    if (appData.data) {//(动态安装参数)
       //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
    }
    if (appData.channelCode) {//(通过渠道链接或二维码安装会返回渠道编号)
        //e.g.可自己统计渠道相关数据等
    }
    if (appData.opCode==OPCode_timeout) {
        //获取参数超时,可在合适时机再去获取(可设置全局标识)
    }
    NSLog(@"OpenInstallSDK:\n动态参数:%@;\n渠道编号:%@",appData.data,appData.channelCode);
}];
//swift引用OC方法时,最好根据系统代码提示来写
OpenInstallSDK.defaultManager()?.getInstallParmsCompleted({ (appData:OpeninstallData?) in
            //在主线程中回调
            if appData?.data != nil {
                //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
            }
            if appData?.channelCode != nil{
                //e.g.可自己统计渠道相关数据等
            }
            if appData?.opCode == OP_Codes.timeout {
                //获取参数超时,可在合适时机再去获取
            }
            print("安装参数 data = \(String(describing: appData?.data)),channelCode = \(String(describing: appData?.channelCode))")
        })

注:
(1) 如果在用户点击“隐私政策”弹窗后去初始化SDK,则需要保证getInstallParmsCompleted方法在初始化方法initWithDelegate之后再调用,防止因为用户操作慢而导致getInstall超时而获取参数失败,也可以使用高级API设置超时时长为30s或以上。
(2) 该方法默认超时为8秒,尽量在业务场景需要参数的位置调用(例如,可以选择在用户注册成功后调用该方法获取参数,对用户进行奖励)。原因是iOS首次安装、首次启动的App,会询问用户获取网络权限,用户允许后SDK才能正常联网去获取参数。如果方法调用过早,网络权限还未被允许,到达超时时间后,会误以为参数不存在(此时getInstallParmsCompleted方法已超时,回调返回为空);
(3) 尽量不要自己保存动态安装参数,在每次需要用到参数时,请调用该方法去获取并处理;

如需手动设置超时时间,请使用高级API:

Object-C
Swift
//高级API,设置超时时长
[[OpenInstallSDK defaultManager] getInstallParmsWithTimeoutInterval:40 completed:^(OpeninstallData * _Nullable appData) {
    if (appData.data) {//(动态安装参数)
        //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
    }
    if (appData.channelCode) {//(通过渠道链接或二维码安装会返回渠道编号)
        //e.g.可自己统计渠道相关数据等
    }
    if (appData.opCode == OPCode_timeout) {
        //代表超时,可做标记,并在合适时机重试
    }
}];
//swift引用OC方法时,最好根据系统代码提示来写
OpenInstallSDK.defaultManager()?.getInstallParms(withTimeoutInterval: 40, completed: { (appData:OpeninstallData?) in
    if appData?.data != nil {
        //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
    }
    if appData?.channelCode != nil {
        //e.g.可自己统计渠道相关数据等
    }
    if appData?.opCode == OP_Codes.timeout {
        //代表超时,可做标记,并在合适时机重试
    }
})

4. 渠道统计高级版功能

SDK 会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。

4.1 注册量统计
如需统计每个渠道的注册量(对评估渠道质量很重要),可根据自身的业务规则,在确保用户完成 App 注册的情况下调用相关api

Object-C
Swift
//用户注册成功后调用
[OpenInstallSDK reportRegister];
//用户注册成功后调用
OpenInstallSDK.reportRegister();

4.2 渠道效果统计

效果点建立在渠道基础之上,主要用来统计终端用户对某些特殊业务的使用效果,如充值金额,分享次数等等。

4.2.1 添加效果点和上报效果值

调用接口前,请先进入管理后台“效果点管理”中添加效果点

效果点管理

调用接口时,请保证代码中的效果点ID与后台创建的效果点ID一致

Object-C
Swift
[[OpenInstallSDK defaultManager] reportEffectPoint:@"效果点ID" effectValue:1];
OpenInstallSDK.defaultManager()?.reportEffectPoint("效果点ID", effectValue:1);

调用接口后,可在后台查看效果点统计数据

4.2.2 渠道效果统计明细

渠道效果统计明细支持开发者添加自定义参数(限添加3个),以便开发者能更好的评估渠道效果和了解用户

调用接口前,请前往“效果点管理”中启用“记录明细”,并添加自定义参数,然后保存

注:明细字典自定义参数的key和value必须是字符串类型

效果点明细

Object-C
Swift
[[OpenInstallSDK defaultManager] reportEffectPoint:@"效果点ID" effectValue:1 effectDictionary:@{@"key01":@"value01",@"key02":@"value02"}];
OpenInstallSDK.defaultManager()?.reportEffectPoint("效果点ID", effectValue:1, effectDictionary: ["key01":"value01","key02":"value02"]);

5.裂变分享高级版功能

分享上报主要是统计某个具体用户在某一次分享中,分享给了哪个平台,再通过JS端绑定被分享的用户信息,进一步统计到被分享用户的激活回流等情况。
注意SDK已经定义好了国内外大部分主流的分享平台,由自定义字符串类型OP_SharePlatform_xxx来传入,也可以传入自定义的平台。

此接口需在用户点击分享按钮或之前触发,才能统计到分享激活或者回流数据。

Object-C
Swift
/**
     * 分享上报
     *
     * @param shareCode 分享用户ID;String 必填,shareCode.length <= 128
     * @param sharePlatform 分享平台:String 建议填入 根据已创建好的“OP_SharePlatform”字符串类型填入
     * @param completedBlock 上报成功则code=0,飞行模式/网络差/连接异常时code=-1可在合适时间进行重试,其它情况代表发送错误
     */
    [[OpenInstallSDK defaultManager] reportShareParametersWithShareCode:@"shareCode001" sharePlatform:OP_SharePlatform_QQ completed:^(NSInteger code, NSString * _Nullable msg) {
        NSLog(@"code = %ld \n msg = %@",(long)code,msg);
        if (code==-1) {
            //飞行模式/网络差/连接异常,可在合适时间进行重试
        }
    }];
OpenInstallSDK.defaultManager()?.reportShareParameters(withShareCode: "shareCode001", sharePlatform: ._WechatSession, completed: { (code, msg) in
        let message = "code = \(code)\n msg = \(msg ?? "")"
            print("code = \(code)\n msg = \(msg ?? "")")
        if code == -1 {
            // 飞行模式/网络差/连接异常,可在合适时间进行重试
            }
    })

四、应用信息配置

SDK集成操作完成后,需要将应用的相关配置信息填充到控制台。填充方式分为:自动配置、手动配置。
自动配置:导出集成完毕的App测试包上传至控制台,上传后系统会自动解析安装包进行信息填充。
手动配置:无需导出App测试包,直接填写对应的应用信息在对应位置后保存即可。

应用信息配置1

应用信息配置2

五、M1、M2芯片mac配置

由于M系列芯片的mac,xcode模拟器支持arm64,但是openinstall sdk不支持这种,会导致编译错误,需要添加一个配置来排除arm64架构的模拟器:

M系列芯片配置