iOS 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,如下代码所示:

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. 快速下载

如果只需要快速下载功能,无需其它功能(携带参数安装、渠道统计、一键跳转),完成初始化即可

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中(通过Xcode自动生成的描述文件,可跳过这一步):

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

2.1.4 在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方法时,最好根据系统代码提示来写
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool{
    //处理通过openinstall一键唤起App时传递的数据
    OpenInstallSDK.continue(userActivity)
    //其他第三方回调:
    return true
}
//注意,swift4.2版本开始,系统方法修改为:
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool{
    OpenInstallSDK.continue(userActivity)
    //其他第三方回调:
    return true
}

2.1.5 如果适配了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)
    }

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以上,会优先走这个方法
    func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
        OpenInstallSDK.handLinkURL(url)
        return true
    }
//注意,swift4.2版本开始,系统方法修改为:
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool{}

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

Object-C
Swift
[[OpenInstallSDK defaultManager] getInstallParmsCompleted:^(OpeninstallData*_Nullable appData) {
    //在主线程中回调
    if (appData.data) {//(动态安装参数)
       //e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
    }
    if (appData.channelCode) {//(通过渠道链接或二维码安装会返回渠道编号)
        //e.g.可自己统计渠道相关数据等
    }
    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.可自己统计渠道相关数据等
            }
            print("安装参数 data = \(String(describing: appData?.data)),channelCode = \(String(describing: appData?.channelCode))")
        })

注:
(1) 尽量不要自己保存动态安装参数,在每次需要用到参数时,请调用该方法去获取并处理;
(2) 该方法默认超时为8秒,尽量在业务场景需要参数的位置调用(例如,可以选择在用户注册成功后调用该方法获取参数,对用户进行奖励)。原因是iOS首次安装、首次启动的App,会询问用户获取网络权限,用户允许后SDK才能正常联网去获取参数。如果方法调用过早,网络权限还未被允许,到达超时时间后,会误以为参数不存在(此时getInstallParmsCompleted方法已超时,回调返回为空);
(3) 如果是业务需要,必须在application:didFinishLaunchingWithOptions即App初始化方法中获取参数,可调用下面高级API,修改超时时长,如果只是拿参数在后台“悄悄地”进行数据统计的情况,超时时长设置为半小时或更长都是ok的,根据需要来。

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

-(void)getInstallParmsWithTimeoutInterval:(NSTimeInterval)timeoutInterval completed:(void (^_Nullable)(OpeninstallData*_Nullable appData))completedBlock;

4. 渠道统计高级版功能

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

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

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

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

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

效果点管理

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

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

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

四、导出apk/ipa包并上传

  • 代码集成完毕后,需要导出安装包上传openinstall后台,openinstall会自动完成所有的应用配置工作。
  • 上传完成后即可开始在线模拟测试,体验完整的App安装/跳转流程;待测试无误后,再完善下载配置信息。

下面是apk包的上传界面(后台截图):

上传安装包