iOS SDK 集成指南
一、导入 SDK
1. CocoaPods导入
在Podfile文件中添加命令: pod 'XinstallSDK'
,执行 pod install
后重新打开项目,完成集成
注意:已经通过 pod 方式集成过 Xinstall,建议先 pod update
来升级本机 pod 仓库,否则会导致获取不到最新版本
如果搜索不到 XinstallSDK,请按下面操作:
1)、先执行: pod setup
2)、再清空搜索索引,让pod重建索引(可能需要等待一会):
rm ~/Library/Caches/CocoaPods/search_ index.json
2. 手动导入
从下载中心下载 iOS 最新版本 SDK 压缩包
解压后,将文件夹导入工程中(导入时请选择 "Copy items if needed" )
二、隐私清单(PrivacyInfo.xcprivacy)
在SDK >= 1.6.1时,SDK会默认包含隐私清单文件,即 PrivacyInfo.xcprivacy
1. 使用CocosPods集成时
pod集成时,当选用版本大于1.6.1时默认在bundle中有该文件
2. 手动集成时
SDK源码中包含了隐私清单文件(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>NSPrivacyCollectedDataTypes</key>
<array/>
<key>NSPrivacyTrackingDomains</key>
<array/>
<key>NSPrivacyTracking</key>
<false/>
<key>NSPrivacyAccessedAPITypes</key>
<array>
<dict>
<key>NSPrivacyAccessedAPIType</key>
<string>NSPrivacyAccessedAPICategoryUserDefaults</string>
<key>NSPrivacyAccessedAPITypeReasons</key>
<array>
<string>CA92.1</string>
</array>
</dict>
</array>
</dict>
</plist>
不使用SDK内的PrivacyInfo.xcprivacy
,共用App的PrivacyInfo.xcprivacy
也是可以的。可将SDK内的条款拷贝到App的PrivacyInfo.xcprivacy
里。
三、初始化
在 AppDelegate 中,增加头文件的引用:
// Swift 开发时,请使用桥接方式引入
#import "XinstallSDK.h"
点击这里,查看如何在 Swift 开发时进行桥接
增加遵守的协议:
@interface AppDelegate ()<XinstallDelegate>
class AppDelegate: UIResponder, UIApplicationDelegate, XinstallDelegate
在 Info.plist 文件中配置 appKey 键值对,如下:
<key>com.xinstall.APP_KEY</key>
<string>xxxxxxx</string>
在 application: didFinishLaunchingWithOptions:
方法中调用 initWithDelegate:
方法来初始化SDK,如下代码所示:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[XinstallSDK initWithDelegate:self];
return YES;
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
XinstallSDK.initWith(self);
return true
}
四、功能集成
1. 快速下载
如果只需要快速下载功能,无需其它功能(携带参数安装、渠道统计、一键拉起),完成初始化即可
2. 一键拉起
Xinstall 通过 Scheme (iOS < 9) 和 Universal Links (iOS ≥ 9) 两种技术,在 App 已安装的情况下,从各种浏览器(包括微信、QQ、新浪微博、钉钉等主流社交软件的内置浏览器)拉起 App 并传递拉起参数。
本文中描述的『唤醒』和『拉起』均指代该业务行为
2.1 通用链接集成(Universal Links)
首先,我们需要到苹果开发者网站,为当前的 App ID 开启关联域名 (Associated Domains) 服务:
为刚才开启关联域名功能的 App ID 创建新的(或更新现有的)描述文件,下载并导入到 Xcode 中(通过 Xcode 自动生成的描述文件,可跳过这一步):
在 Xcode 中配置 Xinstall 为当前应用生成的关联域名(Associated Domains):applinks:xxxx.xinstall.top 和 applinks:xxxx.xinstall.net
具体的关联域名可在 Xinstall管理后台 - 对应的应用控制台 - iOS下载配置 页面中找到
在 AppDelegate 的通用链接(Universal Links)相关方法,添加 Xinstall SDK 提供的处理代码,将拉起参数提交给 XinstallSDK 来处理
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler {
// 判断是否通过Xinstall Universal Link 唤起App
if ([XinstallSDK continueUserActivity:userActivity]) { //如果使用了Universal link ,此方法必写
return YES;
}
// 其他第三方回调;
return YES;
}
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
if XinstallSDK.continue(userActivity) {
return true
} // 如果使用了Universal link ,此方法必写
// 其他第三方回调:
return true
}
// 注意,Swift4.2版本,系统方法修改为:
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
if XinstallSDK.continue(userActivity) {
return true
} // 如果使用了Universal link ,此方法必写
// 其他第三方回调:
return true
}
注意 iOS13 之后如果使用了 SceneDelegate,则需要在 SceneDelegate 内相关方法中添加 Xinstall SDK 提供的处理代码。如果未使用 SceneDelegate,可以直接跳过该配置
// 注意 iOS13 之后如果有 SceneDelegate,则调用的方法需要放 SceneDelegate,低版本暂不支持 SceneDelegate,可以直接跳过该配置
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
// 走 scene 如果是 Universal Links 冷启动不会调用 SceneDelegate 的 - (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity 方法
if (connectionOptions.userActivities.count > 0 ) {
[connectionOptions.userActivities enumerateObjectsUsingBlock:^(NSUserActivity * _Nonnull obj, BOOL * _Nonnull stop) {
if ([XinstallSDK continueUserActivity:obj]) {
*stop = YES;
}
}];
}
}
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
if (![XinstallSDK continueUserActivity:userActivity]) {
// 其他第三方回调
}
}
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
guard let _ = (scene as? UIWindowScene) else { return }
if connectionOptions.userActivities.count > 0 {
for (_, userActivity) in connectionOptions.userActivities.enumerated() {
if XinstallSDK.continue(userActivity) {
break;
}
}
}
}
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
if XinstallSDK.continue(userActivity) {
}
}
2.2 集成Scheme
此方法为 XinstallSDK 1.2.2 最新添加的方法,如果使用报错,请先更新SDK。更多问题见iOS常见问题
2.2.1 在 Xcode 选中Target -> Info -> URL Types,配置 Xinstall 为当前应用生成的 Scheme,如图所示:
上图中的值仅为示例,具体为 xi+appkey 格式,如 xi4z9yxu8,您也可以在iOS集成-功能集成-一键拉起的文档中找到您对应的 Scheme 值
2.2.2 在 AppDelegate 的两个 scheme 回调方法中添加 Xinstall 的 Scheme 方法
// iOS9 以上会走这个方法
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
// 处理通过Xinstall URL SchemeURL 唤起App的数据
[XinstallSDK handleSchemeURL:url];
return YES;
}
// iOS9 以下会走这个方法
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(nullable NSString *)sourceApplication annotation:(id)annotation {
// 处理通过Xinstall URL SchemeURL 唤起App的数据
[XinstallSDK handleSchemeURL:url];
return YES;
}
// iOS9 以上会走这个方法
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
// 处理通过Xinstall URL SchemeURL 唤起App的数据
XinstallSDK.handleSchemeURL(url)
return true
}
// iOS9 以下会走这个方法
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
// 处理通过Xinstall URL SchemeURL 唤起App的数据
XinstallSDK.handleSchemeURL(url)
return true
}
2.2.3 iOS13之后如果有 SceneDelegate,则调用的方法需要放在 SceneDelegate.m
中。如果未使用 SceneDelegate, 可以直接跳过该配置
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
// scheme相关代码
for (UIOpenURLContext *urlcontext in connectionOptions.URLContexts) {
[XinstallSDK handleSchemeURL:urlcontext.URL];
}
}
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
// scheme相关代码
for (UIOpenURLContext *urlcontext in URLContexts) {
[XinstallSDK handleSchemeURL:urlcontext.URL];
}
}
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
guard let _ = (scene as? UIWindowScene) else { return }
// scheme相关代码
for urlcontext: UIOpenURLContext in connectionOptions.urlContexts {
XinstallSDK.handleSchemeURL(urlcontext.url);
}
}
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
// scheme相关代码
for urlcontext in URLContexts {
XinstallSDK.handleSchemeURL(urlcontext.url);
}
}
2.3 添加拉起参数回调方法
在 AppDelegate 中遵守 XinstallDelegate 协议并且添加一键拉起的回调,获取来自 H5页面 的动态参数,根据参数值执行相关操作,如跳转体验页面等
您可以在下述两种回调方法中任选一个进行实现,不同的回调方法有不同的逻辑,请选择最符合您实际场景的方法进行实现,请勿同时实现两个方法。
【方法一】:- (void)xinstall_getWakeUpParams:(nullable XinstallData *)appData;
该方法只会在成功获取到拉起参数时,才会回调。如果无法成功获取到拉起参数,例如不是集成了 Xinstall Web SDK 的页面拉起您的 App 时,将会无法获取到拉起参数,也就不会执行该回调方法。
// 通过 Xinstall 获取已经安装 App 被拉起时的参数(如果是通过渠道页面拉起 App 时,会返回渠道编号)
- (void)xinstall_getWakeUpParams:(nullable XinstallData *)appData {
if (appData.data) { // 拉起参数
// e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
// uo 为H5网址后拼接的参数,如下载地址 https://app.xinstall.com/app/8l4hkz1?channelCode=zhihu&key1=value1&key2=value2,则uo为{channelCode=zhihu;key1=value1;key2=value2};
id uo = [appData.data objectForKey:@"uo"];
// co 为通过H5按钮点击事件传递参数, Xinstall 支持单页面传递多事件参数。
id co = [appData.data objectForKey:@"co"];
}
if (appData.channelCode) { // 通过渠道链接拉起时,会返回渠道编号
// e.g.可自己统计渠道相关数据等
}
NSLog(@"XinstallSDK:\n拉起参数:%@;\n渠道编号:%@", appData.data, appData.channelCode);
}
func xinstall_getWakeUpParams(_ appData: XinstallData?) {
if appData?.data != nil { // 拉起参数
// e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
}
if appData?.channelCode != nil { // 通过渠道链接拉起时,会返回渠道编号
// e.g.可自己统计渠道相关数据等
}
print("唤醒参数 data = \(String(describing: appData?.data)), channelCode = \(String(describing: appData?.channelCode))")
}
【方法二】:- (void)xinstall_getWakeUpParams:(nullable XinstallData *)appData error:(nullable XinstallError *)error;
该方法无论是否成功获取到拉起参数,均会回调。如果成功获取到拉起参数,则 appData != nil 并且 error == nil;如果没有获取到拉起参数,则 appData == nil 并且 error != nil。
// 通过 Xinstall 获取已经安装 App 被拉起时的参数(如果是通过渠道页面拉起 App 时,会返回渠道编号)
- (void)xinstall_getWakeUpParams:(XinstallData *)appData error:(XinstallError *)error {
if (error) {
NSLog(@"没有获取到拉起参数,错误类型:%li,错误描述:%@", (long)error.type, error.errorMsg);
} else {
if (appData.data) { // 拉起参数
// e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
// uo 为H5网址后拼接的参数,如下载地址 https://app.xinstall.com/app/8l4hkz1?channelCode=zhihu&key1=value1&key2=value2,则uo为{channelCode=zhihu;key1=value1;key2=value2};
id uo = [appData.data objectForKey:@"uo"];
// co 为通过H5按钮点击事件传递参数, Xinstall 支持单页面传递多事件参数。
id co = [appData.data objectForKey:@"co"];
}
if (appData.channelCode) { // 通过渠道链接拉起时,会返回渠道编号
// e.g.可自己统计渠道相关数据等
}
NSLog(@"XinstallSDK:\n拉起参数:%@;\n渠道编号:%@", appData.data, appData.channelCode);
}
}
func xinstall_getWakeUpParams(_ appData: XinstallData?, error: XinstallError?) {
if error != nil {
print("没有获取到拉起参数,错误类型:\(String(describing: error?.type)),错误描述:\(String(describing: error?.errorMsg))")
} else {
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 业务中,需要获取到安装参数时,可以调用 getInstallParamsWithCompletion:
方法获取来自H5页面的动态参数。在回调中获取到安装参数后,可以执行下一步业务操作,比如上报渠道信息,直达对应游戏房间,跳转指定页面等:
// 安装App后,通过 XinstallSDK 获取到传递的参数(如果是通过渠道页面安装App时,会返回渠道编号)
[[XinstallSDK defaultManager] getInstallParamsWithCompletion:^(XinstallData * _Nullable installData, XinstallError * _Nullable error) {
if (error == nil) {
// error 为 nil 时代表获取安装参数成功
if (installData.data) { // 安装参数
// e.g. 如免填邀请码绑定邀请关系、自动加好友、自动进入某个群组或房间等
// uo 为H5网址后拼接的参数,如下载地址 https://app.xinstall.com/app/8l4hkz1?channelCode=zhihu&key1=value1&key2=value2,则uo为{channelCode=zhihu;key1=value1;key2=value2};
id uo = [installData.data objectForKey:@"uo"];
// co 通过H5按钮点击事件传递参数, Xinstall 支持单页面传递多事件参数。
id co = [installData.data objectForKey:@"co"];
}
if (installData.channelCode) {// 通过渠道链接或二维码唤醒会返回渠道编号
// e.g.可自己统计渠道相关数据等
}
if (installData.timeSpan > 20 ) {
// e.g. 超过20s不处理
}
if (installData.isFirstFetch) {
// e.g. 第一次获取到安装参数
}
NSLog(@"XinstallSDK:\n动态参数:%@;\n渠道编号:%@", installData.data, installData.channelCode);
} else {
// 获取安装参数时发生错误,具体可根据 error.type 和 error.errorMsg 的值进行下一步处理
}
}];
// 安装App后,通过 XinstallSDK 获取到传递的参数(如果是通过渠道页面安装App时,会返回渠道编号)
XinstallSDK.defaultManager()?.getInstallParams(completion: { (installData: XinstallData?, error: XinstallError?) in
if error == nil {
if installData?.data != nil { // 安装参数
// e.g.如免填邀请码建立邀请关系、自动加好友、自动进入某个群组或房间等
// uo 为H5网址后拼接的参数,如下载地址 https://app.xinstall.com/app/8l4hkz1?channelCode=zhihu&key1=value1&key2=value2,则uo为{channelCode=zhihu;key1=value1;key2=value2};
var uo = installData?.data["uo"];
// co 通过H5按钮点击事件传递参数, Xinstall 支持单页面传递多事件参数。
var co = installData?.data["co"];
}
if installData?.channelCode != nil { // 通过渠道链接或二维码安装会返回渠道编号
// e.g.可自己统计渠道相关数据等
}
if installData != nil && installData!.timeSpan > 20 {
// e.g. 超过20s不处理
}
if installData?.isFirstFetch == true {
// e.g. 第一次获取到安装参数
}
print("唤醒参数 data = \(String(describing: installData?.data)),channelCode = \(String(describing: installData?.channelCode))")
} else {
// 获取安装参数时发生错误,具体可根据 error.type 和 error.errorMsg 的值进行下一步处理
}
})
【注意】若 installData 不为空,但 installData.channelCode 为空时,代表本次安装不来自于渠道
您可以在 Xinstall 管理后台对应的 App 内,看到所有的传递参数以及参数出现的次数,方便你们做运营统计分析,如通过该报表知道哪些页面或代理带来了最多客户,客户最感兴趣的 App 页面是什么等。具体参数名和值,运营人员可以和技术协商定义,或联系 Xinstall 客服咨询。具体效果如下图:
4. 高级数据统计
SDK初始化时会自动完成访问量、点击量、安装量、活跃量、留存率等统计工作。 除此之外我们还提供了以下三种数据统计服务:
注册量统计
如需统计每个渠道的注册量(对评估渠道质量很重要),可根据自身的业务规则,在确保用户完成 App 注册的情况下调用如下方法,即可上报一次注册量:
// 用户注册成功后调用
[XinstallSDK reportRegister];
// 用户注册成功后调用
XinstallSDK.reportRegister()
您可在 Xinstall 管理后台对应的 App 的『渠道报表』页面中查看每个渠道上报的注册量
事件统计
事件统计,主要用来统计终端用户对于某些特殊业务的使用效果,如充值金额,广告浏览次数等等。
调用接口前,需要先进入管理后台事件统计然后点击新增事件
调用接口时,需要保证代码中的事件ID与后台创建的事件ID一致
[[XinstallSDK defaultManager] reportEventPoint:@"事件ID" eventValue:123];
XinstallSDK.defaultManager()?.reportEventPoint(@"事件ID", eventValue: 123)
注:只有后台创建事件统计,并且代码中传递的事件ID与后台创建的ID一致时,上报数据才会被统计.
您可以设置不同事件来满足不同的业务场景,如下图所示,您可以设置充值事件,进行上报。就可以统计到总的充值设备数为32个,累积充值金额为364元
事件明细统计
除了旧有事件业务,我们还开发了事件明细统计,用来统计各个事件具体发生情况
在使用之前要现在后台管理系统中打开该事件明细统计功能,具体如下:
在开启权限之后,我们直接使用Xinstall SDK 的- (void)reportEventWhenOpenDetailInfoWithEventPoint:(NSString *)eventID eventValue:(long)eventValue subValue:(NSString *)subValue
方法上传单个事件的第二个详细值
[[XinstallSDK defaultManager] reportEventWhenOpenDetailInfoWithEventPoint:@"事件ID" eventValue:123 subValue:@"事件详情值(如用户名)"];
XinstallSDK.defaultManager()?.reportEventWhenOpenDetailInfo(withEventPoint: "事件ID", eventValue: 123, subValue: "事件详情值(如用户名)")
最终在事件列表中可以点击查看查阅具体详情的内容
5. 场景定制统计
5.1 分享统计
场景业务介绍,可到分享数据统计页面查看
分享统计主要用来统计分享业务相关的数据,例如分享次数、分享查看人数、分享新增用户等。在用户分享操作触发后(注:此处为分享事件触发,非分享完成或成功),可调用如下方法上报一次分享数据:
[[XinstallSDK defaultManager] reportShareByXinShareId:@"填写分享人或UID"];
XinstallSDK.defaultManager()?.reportShare(byXinShareId: "填写分享人或UID")
注:分享人或UID 可由您自行定义,只需要用以区分用户即可
您可在 Xinstall 管理后台 对应 App 中查看详细分享数据报表,表中的「分享人/UID」即为调用方法时携带的参数,其余字段含义可将鼠标移到字段右边的小问号上进行查看:
五、导出ipa包并上传
上传 ipa 包时,我们会帮您做 SDK 集成配置判断,如果符合标准,则可以点击上传,如果存在相关警告,则需要您注意相关设置。