iOS用户运营SDK集成

iOS用户运营SDK集成

使用Xcode15的开发者请注意:
由于Xcode15在target<12下会存在Network.framework Crash问题。
解决方案一:用户需要升级使用GTCommonSDK 3.1.0.0+, SDK新增在Info.plist中添加GT_MinimumOSVersion字段,填写当前app的target值。对应的通知扩展的Info.plist也需要同样的修改。
解决方案二:修改target>=12。 苹果官网明确Xcode15最低支持iOS12+。

版本更新说明

2.0.5.0 版本更新注意:

  • 用户运营 IDOSDK 2.0.5.0 开始支持隐私清单和SDK签名;GTCommonSDK 3.1.0.0 开始支持隐私清单和SDK签名。

2.0.4.0版本更新注意:

  • 由于Xcode15在target<12下会存在Network.framework Crash问题,SDK新增在Info.plist中添加GT_MinimumOSVersion字段,填写当前app的target值。
  • 需要集成GTCommonSDK 3.1.0.0及以上版本。

1.1. CocoaPods 集成(推荐)

  • 使用时需要新建一个名为 Podfile 的文件,如下格式,将依赖的库名字依次列在文件中即可:
target 'GtSdkDemo' do
    platform :ios, "8.0"
    pod 'GTCommonSDK'
    pod 'GCIDOSDK'
end

注意:用户运营2.0.0.0及以上版本,需要集成GTCommonSDK 3.0.0.0及以上版本。

  • 将编辑好的 Podfile 文件放到你的项目根目录中,执行如下命令即可:
$ cd "<path/to/project>"
$ pod install

1.2. 手动集成

1.2.1. 导入 SDK

  • SdkLib目录拷贝到项目工程目录下,导入SdkLib文件夹:

1.2.2. 库引用检查

  • 在导入时,Xcode正常情况下会自动添加引用,但是偶尔也会不添加,注意检查下图中的引用路径,如果报错找不到库或者头文件,一般都是下面的引用没有添加,请在$(inherited)下面添加你的framwork路径。

1.2.3. 添加系统依赖库

  • 在项目设置中添加以下系统库支持:
libc++.tbd
libz.tbd
libsqlite3.tbd
libresolv.tbd
Security.framework
MobileCoreServices.framework
SystemConfiguration.framework
CFNetwork.framework
CoreTelephony.framework
CoreLocation.framework
AdSupport.framework(如果需要采集idfa请添加此库并按照苹果要求进行申请)

1.2.4. 设置 Other Linker Flags

找到主工程的 target -> Build Setting -> Linking -> Other Linker Flags,在$(inherited)下面添加 -ObjC

配置权限

在此之外,您还可以配置以下可选权限,以便使用地理位置等相关的标签和特征,如居住城市标签等用于人群圈选和画像洞察,为精细化运营提供必要数据支撑。

可在项目的Info.plist中配置如下:


  <!-- 允许访问网络 -->
  <key>NSAppTransportSecurity</key>
  <dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
  </dict>

  <!-- IDFA -->
  <key>NSUserTrackingUsageDescription</key>
  <string>请求IDFA描述</string>

  <!-- 定位相关 -->
  <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
  <string>根据业务需要,始终允许访问位置信息</string>
  <key>NSLocationAlwaysUsageDescription</key>
  <string>根据业务需要,始终允许访问位置信息</string>
  <key>NSLocationUsageDescription</key>
  <string>根据业务需要,永不允许访问位置信息</string>
  <key>NSLocationWhenInUseUsageDescription</key>
  <string>根据业务需要,使用应用期间允许访问位置信息</string>

2.集成代码

2.1. 初始化启动接口

接口描述:

使用统计功能以前,需要先启动 SDK,该接口用于在 App 运行时启动数据统计 SDK。

接口定义:

/**
 初始化启动接口

 @param appId 开发者中心生成的 appId
 @param channelId 渠道名称,默认为 'appstore'
 */
+ (void)startSDKWithAppId:(NSString *)appId withChannelId:(NSString *)channelId;

接口说明:

AppDelegate didFinishLaunchingWithOptions 方法中:通过平台分配的 APPID 启动统计 SDK。

参数 参数说明
appId 应用标识 APPID
channelId 渠道名称,如果为 nil或者空串,默认为 'appstore'

接口示例:

#import <GTCountSDK/GTCountSDK.h>
#define kGcAppId @"xxxxxxx"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 启动数据统计 SDK
   [GTCountSDK startSDKWithAppId:kGcAppId withChannelId:@"appstore"];
   return YES;
 }

2.2. 开启debug模式

接口描述:

SDK默认不打印信息,发布版本时请关闭debug模式,以免影响性能。

接口定义:

/**
 是否启动开发者模式,在该模式下会打印相关的数据上传信息

 @param isDebug 是否开启
 */
+ (void)setDebugEnable:(BOOL)isDebug;

接口示例:

#import <GTCountSDK/GTCountSDK.h>
#define kGcAppId @"xxxxxxx"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 启动数据统计 SDK
   [GTCountSDK setDebugEnable:YES];
   [GTCountSDK startSDKWithAppId:kGcAppId withChannelId:@"appstore"];
   return YES;
 }

2.3. 应用活跃时长统计

应用时长统计用于统计启动次数和应用的真实活跃时长,集成 SDK 后不需要开发者调用额外的接口。

其中 iOS 平台一次完整的启动包括如下两种情况:

1.从启动应用到关闭应用

2.从启动应用到应用退至后台,且在后台时间超过 30s 。可以修改该默认值:

    [GTCountSDK sharedInstance].sessionTime = 30*1000;

2.4. 自定义事件

自定义事件可以统计某些用户自定义埋点的发生时间以及次数,例如广告点击、短信数量等。通常 event_id用于表示某种行为或功能的统计(如统计“发送”按钮被触发多少次),而参数则用于标识统计的具体对象(如功能为“下载”的按钮),由 event_id 唯一标识一个事件。

自定义事件主要分为三种:

(1)次数统计:统计指定行为被触发的次数。

(2)时长统计:统计指定行为消耗的时间,单位为毫秒。需要 eventBegineventEnd 接口成对使用才可生效。

(3)用户属性统计:统计对应用户的相关信息。

每类事件都支持使用 NSDictionary 参数类型。其中 key 必须为 NSString 类型,value 仅支持NSNumber, BOOL, NSString, NSDate 4 种类型。

注意事项:
1.自定义参数设置后,类型以第一次上报为准。如果类型不一致,则数据会上报失败。如果遇到问题,请联系技术支持。
2.不管是事件的唯一标识event_id还是属性里的key 类型都为字符串类型,且不能出现空格、回车等特殊字符,也不可以$开头($开头的是SDK的预置属性和预置属性,具体见文末)。

2.4.1. 次数统计事件

接口描述:

在事件执行时调用次数统计方法,SDK 会根据事件 Id ,统计该事件被点击的次数。

接口定义:

/**
 计数事件统计

 @param eventId 事件 Id
 @param args 自定义属性,key 必须为 NSString 类型(注意:不能以$开头),value 仅支持NSNumber, BOOL, NSString, NSDate 4 种类型
 @param ext 内部字段,不建议使用。
 */
+ (void)trackCountEvent:(NSString *)eventId withArgs:(NSDictionary *) withExt:(NSString *)ext;

接口参数说明:

参数 参数说明
eventId 自定义事件 Id
args ⾃定义属性,key 必须为 NSString 类型(注意:不能以$开头),value 仅支持NSNumber, BOOL, NSString, NSDate 4 种类型
ext 内部字段,不建议使用

接口示例:

@implementation TrackCountEventController
 - (IBAction)clickCount:(id)sender {
    [GTCountSDK trackCountEvent:@"test" withArgs:@{@"time":[NSDate date],@"number":@(34.0),@"string":@"str",@"BOOL":@YES} withExt:nil];
 }
 @end

2.5. 用户属性设置

接⼝描述:

设置用户属性,记录的是用户的基本固定不变的属性,例如性别、出生年份、注册时间、注册地域、注册渠道等。

接⼝定义:

/**
用户属性设置
@param profiles ⽤户属性参数,key 必须为 NSString 类型,value 仅支持NSNumber, BOOL, NSString, NSDate 4 种类型。
*/
 + (void)setProfile:(NSDictionary *)profiles;

接⼝示例:

NSMutableDictionary *profiles = [NSMutableDictionary new]; 
[profiles setObject:@"username001" forKey:@"$name"]; 
[profiles setObject:@"男" forKey:@"$sex"];
[GTCountSDK setProfile:profiles.copy];
return YES;

2.6. 获取gtcid

接⼝描述:

您可通过下面的方法获取gtcid,gtcid可用于用户画像标签的查询。

接⼝定义:

/// gtcid可用于用户画像标签的查询。
+ (NSString*)gtcid;

接⼝示例:

NSLog(@"gtcid:%@", [GTCountSDK gtcid]);

3.预置事件说明

预置事件主要应用于系统中所有事件相关功能,如app_start 可在事件分析、用户群等模块选用,进行对应的分析。
预置事件由SDK自动采集填充,开发者不可修改。

事件名称 描述 说明
sys_$app_start 启动app 不区分前后台
sys_$foreground_start 打开app 仅前台

4.预置属性说明

预置属性中包含日常分析常用的一些维度,会由SDK自动采集,系统的看板等功能中会用到这些预置属性用于筛选分析。

统计事件预置属性

统计事件的预置属性由sdk自动采集填充,开发者不可以修改:

字段名称 类型 说明
sys_$wifi 布尔值 是否使用wifi
sys_$carrier 字符串 运营商名称
sys_$network_type 字符串 网络类型
sys_$app_version 字符串 应用版本
sys_$lib_version 字符串 SDK版本
sys_$manufacturer 字符串 设备制造商
sys_$model 字符串 设备型号
sys_$os 字符串 操作系统
sys_$os_version 字符串 操作系统版本
sys_$package_name 字符串 应用包名
用户属性事件预置属性

用户属性事件的预置属性分为两部分。一部分是由SDK自动采集填充的,如下表:

字段名称 类型 说明
sys_$app_version 字符串 应用版本
sys_$channelId 字符串 渠道
sys_$lib_version 字符串 SDK版本
sys_$manufacturer 字符串 设备制造商
sys_$model 字符串 设备型号
sys_$os 字符串 操作系统
sys_$os_version 字符串 操作系统版本
sys_$screen_width 数值 屏幕宽度
sys_$screen_height 数值 屏幕高度
sys_$firstvisittime 日期 首次访问时间
sys_$package_name 字符串 应用包名

另一部分需由用户手动设置,如下表:

字段名称 类型 说明
sys_$country 字符串 国家
sys_$city 字符串 城市
sys_$province 字符串 省份
sys_$name 字符串 姓名
sys_$sex 字符串 性别
sys_$phone 字符串 手机号
sys_$email 字符串 邮箱
sys_$birthday 日期 出生日期
sys_$signup_time 日期 注册时间

5.隐私文件和SDK签名

用户运营SDK 3.0.5.0开始支持隐私文件和SDK签名。GTCommonSDK 3.1.0.0开始支持隐私文件和SDK签名。
下载SDK,解压后查看PrivacyInfo.xcprivacy文件。

GTIDO_IOS_SDK/
  |- SdkLib/ 
  |   |- GTCountSDK.xcframework
  |   |    |- ios-对应cpu架构
  |   |    |   |- GTCountSDK.framework
  |   |    |   |   |- PrivacyInfo.xcprivacy
  |   |- GTCommonSDK.xcframework
  |   |    |- ios-对应cpu架构
  |   |    |   |- GTCommonSDK.framework
  |   |    |   |   |- PrivacyInfo.xcprivacy

文档中心搜索

技术
咨询

微信扫一扫

随时联系技术支持

在线
咨询