iOS SDK集成文档（原生开发）

集成引言

为了保证您的应用能正常通过应用市场上架审核，请在App的《隐私政策》中加入openinstall SDK会获取的设备信息、用途以及使用范围，具体内容可参考《合规指南》或官网的《隐私政策》。用户同意App的《隐私政策》之后再进行SDK初始化，如不同意则不能进行初始化。

一、导入 SDK

1. CocoaPods导入

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

备注：建议先pod repo update或pod 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" )

二、隐私清单(PrivacyInfo.xcprivacy)

在SDK >= 2.8.3时，SDK会默认包含隐私清单文件，即PrivacyInfo.xcprivacy

1、使用CocoaPods集成时

pod集成SDK时，提供了隐私清单文件（PrivacyInfo.xcprivacy），是bundle形式存在的，可能会导致在xcode14之后编译提示未签名的错误：
Signing for "libOpenInstallSDK-OPPrivacy" requires a development team.

可以在Podfile文件中做如下配置，然后重新pod install（推荐）：

post_install do |installer|
   installer.pods_project.targets.each do |target|
       if target.respond_to?(:product_type) and target.product_type == "com.apple.product-type.bundle"
          target.build_configurations.each do |config|
            config.build_settings['CODE_SIGN_IDENTITY'] = ''
            config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
          end
       end
    end
end

2、手动集成时

SDK源码中包含了隐私清单文件（PrivacyInfo.xcprivacy），请注意需要将源代码目录下的PrivacyInfo.xcprivacy拷贝进您的代码工程里，PrivacyInfo.xcprivacy内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>CA92.1</string>
            </array>
        </dict>
    </array>
    <key>NSPrivacyCollectedDataTypes</key>
    <array/>
    <key>NSPrivacyTracking</key>
    <false/>
    <key>NSPrivacyTrackingDomains</key>
    <array/>
</dict>
</plist>

开发者也可以直接将SDKPrivacyInfo.xcprivacy中的条款复制并补全到自己App的PrivacyInfo.xcprivacy里

三、初始化

在Info.plist文件中配置appKey键值对，如下：

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

在AppDelegate中，增加头文件的引用：

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

在AppDelegate中遵守OpenInstallDelegate协议，参考如下：

@interface AppDelegate ()<OpenInstallDelegate>
@end

class AppDelegate: UIResponder, UIApplicationDelegate, OpenInstallDelegate {
}

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

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

- (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）服务：

2.1.2 在 Xcode 中配置 openinstall 为当前应用生成的关联域名（Associated Domains）：

2.1.3 在AppDelegate中添加通用链接（Universal Links）回调方法，委托给 openinstall 来处理

- (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可忽略）：

//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这个方法中处理第三方回调的时候（比如支付宝回调，微信回调等），请注意区分

//适用目前所有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可忽略）：

//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 页面的动态参数，根据参数值直达具体页

//通过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方法，在回调中获取参数（可重复获取）

[[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:

//高级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

//用户注册成功后调用
[OpenInstallSDK reportRegister];

//用户注册成功后调用
OpenInstallSDK.reportRegister();

4.2 渠道效果统计

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

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

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

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

[[OpenInstallSDK defaultManager] reportEffectPoint:@"效果点ID" effectValue:1];

OpenInstallSDK.defaultManager()?.reportEffectPoint("效果点ID", effectValue:1);

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

4.2.2 渠道效果统计明细

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

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

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

[[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来传入，也可以传入自定义的平台。

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

/**
     * 分享上报
     *
     * @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测试包，直接填写对应的应用信息在对应位置后保存即可。

六、M1、M2芯片mac配置

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