埋点API

1 如何查看埋点方案

在进行埋点前,需要确定在哪里埋点、埋哪些点等,即需要梳理清楚明确的埋点需求。在QuickTracking平台中将明确的埋点需求称为埋点方案,并为埋点方案设计了规范模板。如下:

image

在埋点方案中,明确的所需埋点内容有:

1、事件主体:指“谁”触发了这个事件,分为设备ID账号ID,上报的事件务必具备其中之一。

  • 设备ID:Android设备和iOS设备的默认设备ID为应用级别唯一的设备ID,由Quicktracking自动生成

    • Android9及以下设备:SDK自动采集imei、wifimac、androidid、SN生成设备ID,生成后存入本地,只有卸载应用或者删除应用数据才会重新生成设备ID。

    • Android10级以上设备:SDK自动采集oaid、gaid、androidid、SN生成设备ID,生成后存入本地,只有卸载应用或者删除应用数据才会重新生成设备ID。

    • iOS设备:SDK自动采集openudid生成设备ID,生成后放入keychain中,只有恢复出厂设置或者删除应用数据才会重新生成设备ID。

    • 使用应用的C端用户同意采集idfa和oaid,QuickTracking SDK才会采集,只有QuickTracking app SDK可以采集到oaid、gaid、imei、wifimac、androidid、SN、idfa、idfv。

  • 账号ID:客户端用户登录后账号标识,当一个用户在不同的设备进行登录时,设备ID会发生变化,但是账号ID不会发生变化。例如一个用户使用手机和pad分别登录。

2、用户属性:针对账号ID的属性,例如账号ID为“testdemo@111”的用户,“生日”为“1999-02-13”,“会员等级”为“铂金”等。“生日”和“会员”等级就为用户属性。

3、渠道属性:广告投放的属性,例如投放渠道、投放方式、投放内容等。

4、全局属性:在全局设置一次后,每一个事件都会携带的属性

5、页面浏览事件:页面加载时上报的事件(埋点方案中页面编码和事件编码相等的事件,也是标记为蓝色的事件)

6、点击、曝光、自定义事件:客户端用户与客户端发生任意交互时上报的事件。

2 设置设备ID&账号ID

2.1 设备ID设置

SDK 内部默认会采集如下参数。

设备标识或设备信息

采集方法

备注

idfa

[ASIdentifierManager advertisingIdentifier].UUIDString

苹果广告标识

idfv

[[UIDevice currentDevice].identifierForVendor UUIDString]

应用级标识

openudid

[UIPasteboardpasteboardWithName:slotPBid create:NO]

openUdid(三方)

淘宝utdid

[UTDevice utdid]

若您集成了淘宝utdid SDK,QuickTracking才会采集

mcc

[UMUtils mccString]

移动信号国家码

mnc

[UMUtils mncString]

移动网络号码

如果开发者希望针对上表中的某几个设备标识符采集行为做控制,如:不采集或自行实现采集方法。可以实现对应block回调,如下示例:

[QTConfigure customSetIdfaBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetIdfvBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetOpenUdidBlock:^NSString *{
  return @"custom-openudid";
}];
[QTConfigure customSetUtdidBlock:^NSString *{
  return @"custom-utdid";
}];
[QTConfigure customSetMccBlock:^NSString *{
  return @"custom-mcc";
}];
[QTConfigure customSetMncBlock:^NSString *{
  return @"custom-mnc";
}];

注意:请谨慎决定是否实现对应方法,一旦您选择自己实现采集方法,此设备标识的采集工作就由你全权接管了,SDK不会再试图采集此设备标识。SDK能采集到的设备标识越少,对统计数据的准确性和稳定性的负面影响越大。

// 请在设置收数域名之前,调用SDK预初始化函数之前,先调用采集工具类注册函数
// 如果不需要对设备标识采集行为做控制,就不需要实现自定义工具类并注册它
[QTConfigure customSetIdfvBlock:^NSString *{
    return [[UIDevice currentDevice].identifierForVendor UUIDString];
}];
[QTConfigure setCustomDomain:@"您的收数域名" standbyDomain:nil];
[QTConfigure initWithAppKey:@"您的appkey" channel:@"App Store"];

SDK支持自定义设备ID,如果要使用自定义设备ID需要在初始化前(即init前) 设置setCustomDeviceId:接口为有效值(非空)。

+ (void)setCustomDeviceId:(NSString *)devID;

使用示例:

[QTConfigure setCustomDeviceId:@"xxxxxx"];

注意:因该功能在未获取到设备ID时生效,如果本地已存在设备ID,设置后无效。如果本地已获取到设备ID可以通过卸载重装方式验证此功能。

2.2 账号ID设置

1、QT在统计用户时以设备为标准,如果需要统计应用自身的账号,请使用以下接口:

接口函数:

+ (void)profileSignInWithPUID:(NSString *)puid;

参数:

参数

类型

描述

备注

puid

NSString

用户账号ID

长度小于64字节

注意:账号ID设置后将被存入本地存储,只有卸载App、清空应用数据或者调用下述的登出接口时,账号ID才会失效,否则每一个事件都将携带账号ID。

示例代码:

[QTMobClick profileSignInWithPUID:@"UserID"];

如果不再需要绑定用户账号,可以调用登出接口,调用后,不再发送账号相关内容。

+ (void)profileSignOff;

示例代码:

[QTMobClick profileSignOff];

2.3 设备ID获取

接口函数:

+ (NSString *)umidString;

示例代码:

NSString *deviceID = [QTConfigure umidString];

3 用户属性上传

1、使用事件编码固定为"$$_user_profile"的自定义事件上传,该事件所携带的事件属性会被作为用户属性放在用户表中。

NSDictionary *dict = @{@"sex" : @"girl", @"age" : @"8"};
[QTMobClick event:@"$$_user_profile" attributes:dict];

请注意:用户属性上传一定要在账号统计调用后

4 渠道属性

4.1 H5链接唤起App

  1. 唤起App的URL Scheme中携带这些渠道属性,且属性key务必以“utm_”开头,因为SDK识别的关键字为“utm_”。例如:<URL scheme>?utm_channel=gzh

  2. 添加您的 URL Scheme 到项目中,URL Scheme 位于项目设置 target ->选项卡 Info ->URL Types。填入的scheme。在AppDelegate中调用函数[MobClick handleUrl:url]来接收 URL

AppDelegate调用:

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
 if ([QTMobClick handleUrl:url]) {
 return YES;
 }

 return YES;
}

SceneDelegate调用:

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

 for (UIOpenURLContext *context in connectionOptions.URLContexts) {
 [QTMobClick handleUrl:context.URL];
 }
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

 [QTMobClick handleUrl:URLContexts.allObjects.firstObject.URL];
}

PS:如果渠道属性已经与市面上渠道投放公司进行了合作,无法使用utm_开头,可以使用全局属性API将渠道属性进行埋点上报(属性key依然需要以“utm_”开头)。

4.2 H5链接唤起应用市场下载并启动App

该场景下,如果仅是H5链接中携带“utm_”参数,已经无法做到下载App后的启动事件携带“utm_”参数。所以需要进行“H5唤起事件”与“应用激活事件”做关于“IP地址和浏览器UserAgent”的模糊匹配。

  1. 当用户在H5中点击「唤起/下载App」的按钮时,上报“应用唤起事件($$_app_link)”,在事件中需要携带唤起App的appkey和渠道属性。

//示例
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: '要唤起的应用appKey',  // 必填,要唤起的应用appKey
    custom1: 'custom1', // 选填,自定义参数
    ...
  }]
})
  1. App下载后的第一次启动事件“应用激活事件($$_app_install)”由QT App SDK自动采集上报。

  2. QuickTracking系统进行应用唤起事件($$_app_link)和应用激活事件($$_app_install)关于“IP地址和浏览器UserAgent”的模糊匹配。您使用时,可以直接在app应用中分析“应用激活(预置)”的渠道属性即可。

4.3 App各应用市场活跃数据统计

在初始化函数中的第二个入参Channel即为设置该应用的应用市场:[QTConfigure initWithAppkey:@"您的appkey" channel:@"App Store"];,在分析中可使用“系统属性-升级渠道”查看。

5 全局属性

注册全局属性后,后续触发的所有事件都将自动包含这些属性,并且这些属性及属性值存入缓存,APP进程结束后清除。在分析数据时,可根据此属性进行查看和筛选。

5.1 注册全局属性

/**
 * 设置全局属性 键值对 
 * 如果和已经存在的全局属性key重复,则更新已有值
 * 如果和已经存在的全局属性key不一致,则插入新的全局属性
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

参数

类型

描述

备注

property

NSDictionary

全局属性的属性名称和属性值

-

示例:

NSDictionary *firstPropertyDict = @{
     @"a" : @"1",
     @"b" : @"2"
};
[QTMobClick registerGlobalProperty:firstPropertyDict];//当前globalproperty为a:1和b:2
    
NSDictionary *secondPropertyDict = @{
     @"b" : @"3",
     @"c" : @"4"
};
[QTMobClick registerGlobalProperty:secondPropertyDict];//当前globalproperty为a:1、b:3和c:4

5.2 获取一个全局属性

/**
 * 获取一个全局属性;如果不存在,则返回空。
 */
+(NSString *) getGlobalProperty:(NSString *)propertyName;

参数

类型

描述

备注

propertyName

NSString

属性名,只支持大小写字母、数字及下划线!

-

返回值

NSString

-

5.3 删除一个全局属性

删除一个特定的全局属性,删除后,后续触发的所有事件都不再携带该属性。

/**
 *
 * 删除指定全局属性
 @param key
 */
+(void) unregisterGlobalProperty:(NSString *)propertyName;

参数

类型

描述

备注

propertyName

NSString

属性名,只支持大小写字母、数字及下划线!

-

5.4 获取所有全局属性

/**
 * 获取所有全局属性;如果不存在,则返回空。
 */
+(NSDictionary *)getGlobalProperties;

参数

类型

描述

备注

返回值

NSDictionary

返回的全局属性值类型为字符型,必须和注册此全局属性时传入参数类型一致。

-

5.5 清除所有的全局属性

/**
 * 清空所有全局属性。
 */
+(void)clearGlobalProperties;

6 页面浏览事件API

SDK提供页面自动采集和页面手动采集两种方式上报页面浏览事件,两种方式也可以混用。

6.1 页面自动采集

页面自动采集是hook系统viewWillAppear和viewWillDisappear,获取className 实现。SDK默认不开启页面自动采集,如果需要开启,建议在初始化之前调用。

接口函数:

+ (void)setAutoPageEnabled:(BOOL)value;

参数

类型

描述

备注

value

BOOL

是否开启页面自动采集

  • YES:开启

  • NO:关闭 (默认关闭)

示例代码:

//设置为开启页面自动采集
[QTMobClick setAutoPageEnabled:YES];

6.1.1 禁止单个页面的自动上报

如果全局设置了开启页面自动采集,可以通过此接口设置跳过单个页面的自动采集。建议在viewWillAppear最开始调用,如只不统计当前自动页面采集,可以将pageName参数设置成nil。

接口函数:

+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

示例:

#import <QTCommon/UMSpmHybrid.h>

- (void)viewWillAppear:(BOOL)animated
{
  
    [super viewWillAppear:animated];

    //不统计当前class自动页面采集
    [UMSpmHybrid skipMe:[self class] pageName:nil];
}

6.2 页面手动采集

接口函数:

/** 自动页面时长统计, 开始记录某个页面展示时长.
 使用方法:必须配对调用beginLogPageView:和endLogPageView:两个函数来完成自动统计,若只调用某一个函数不会生成有效数据。
 在该页面展示时调用beginLogPageView:,当退出该页面时调用endLogPageView:
 @param pageName 统计的页面名称.
 @return void.
 */
+ (void)beginLogPageView:(NSString *)pageName;

/** 自动页面时长统计, 结束记录某个页面展示时长.
 使用方法:必须配对调用beginLogPageView:和endLogPageView:两个函数来完成自动统计,若只调用某一个函数不会生成有效数据。
 在该页面展示时调用beginLogPageView:,当退出该页面时调用endLogPageView:
 @param pageName 统计的页面名称.
 @return void.
 */
+ (void)endLogPageView:(NSString *)pageName;

参数:

参数

类型

描述

备注

pageName

NSString

统计的页面编码

beginLogPageView 和 endLogPageView中的值必须一致

注意:

  • 必须配对调用beginLogPageView:和endLogPageView:两个函数来完成自动统计,若只调用某一个函数不会生成有效数据;

  • 在该页面展示时调用beginLogPageView:,当退出该页面时调用endLogPageView:。

示例代码:

在ViewController类的viewWillAppear: 和 viewWillDisappear:中配对调用如下方法:

- (void)viewWillAppear:(BOOL)animated
{
 [super viewWillAppear:animated];
 [QTMobClick beginLogPageView:@"Pagename"]; //("Pagename"为页面名称,可自定义)
}

- (void)viewWillDisappear:(BOOL)animated 
{
 [super viewWillDisappear:animated];
 [QTMobClick endLogPageView:@"Pagename"];
}

您也可以根据您自己的业务场景,在viewDidAppear:和viewDidDisappear:等方法中配对调用beginLogPageView:和endLogPageView:两个函数来完成自动统计。

6.2.1 页面属性设置

iOS端页面属性设置接口updatePageProperties,支持给当前页面附加自定义属性。 接口:

/**
 * @brief 更新页面业务参数.
 *
 * @param pageName 页面名称,如Page_Detail
 * @param pProperties 业务参数,kv对
 *
 * @warning 调用说明:必须在viewWillDisappear之前调用
 *
 * 最佳位置:在viewWillDisappear之前调用即可
 */
+(void) updatePageProperties:(NSString *)pageName properties:(NSDictionary *) pProperties;

参数:

参数

类型

描述

备注

pageName

NSString

页面编码,如Page_Detail

pProperties

NSDictionary

业务参数,kv对

请注意:请在调用beginLogPageView之后设置页面属性。

引入头文件:

#import <QTCommon/UMSpm.h>

示例:

[UMSpm updatePageProperties:@"page_home" properties: @{@"page_home_key":@"page_home_val"}];

请注意:页面属性设置只支持页面手动埋点

6.2.2 透传页面属性

此外,QuickTracking SDK还提供透传页面属性埋点接口updateNextPageProperties,支持给下一个页面附加自定义属性。

/**
 * @brief  更新下一个页面业务参数.
 *
 * @param properties 传给下一个页面业务参数,kv对
 *
 * @warning  调用说明:必须在下一个页面pageAppear之前调用,否则会携带错误
 *
 * 最佳位置:必须在下一个页面pageAppear之前调用
 */
+(void) updateNextPageProperties:(NSDictionary *) properties;

参数:

参数

类型

描述

备注

properties

NSDictionary

传给下一个页面业务参数,kv对

示例:

必须在下一个页面beginLogPageView之前调用。

[UMSpm updateNextPageProperties:@{@"news_next_key":@"news_next_val"}];

请注意:透传页面属性只支持页面手动埋点

7 事件埋点

自定义事件可以用于追踪用户行为,记录行为发生的具体细节。

7.1 事件埋点

接口:

+ (void)event:(NSString *)eventCode; 

+ (void)event:(NSString *)eventCode attributes:(NSDictionary *)attributes;

+ (void)event:(NSString *)eventId pageName:(NSString *)pageName attributes:(NSDictionary *)attributes;

参数说明:

参数

类型

描述

备注

eventCode

NSString

事件编码

埋点方案中点击、曝光、自定义事件的事件编码

attributes

NSDictionary

自定义属性

-属性中的key的value不可以是空

-value的类型只能是String、Long、Integer、Float、Double、Short,或数组(数组中的元素必须为String)类型。

pageName

NSString

页面编码

事件所在页面,埋点方案中点击、曝光、自定义事件的所在页面编码。

事件上传数量限制:

  • 自定义属性key字符串长度上限:1024

  • 自定义属性value字符串长度上限:1024*4

  • 自定义属性map长度(参数个数):100 个键值对

  • 当自定义属性值value为数组元素时,属性值的数组长度上限:100

  • 单条日志报文的总长度限制:2MB

示例1:

统计应用中”转发”事件发生的次数,那么在转发的函数里调用:

[QTMobClick event:@"Forward"];

示例2:

统计应用中“购买”事件发生的次数,以及购买的商品类型及数量,那么在购买的函数里调用:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" attributes:dict];

示例3:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" pageName:@"ViewController" attributes:dict];

8 全埋点(自动埋点)

8.1 全埋点适用范围

SDK适用于iOS 8.0及以上操作系统。

8.2 全埋点接口说明

8.2.1 自动页面采集接口

说明

自动采集页面是hook系统viewWillAppear和viewWillDisappear,获取className 实现,建议在初始化之前调用,默认是关闭

/** 设置是否自动采集页面, 默认NO(不自动采集).
 @param value 设置为YES, QT SDK 会自动采集页面信息
 */
+ (void)setAutoPageEnabled:(BOOL)value;

示例:

 [QTMobClick setAutoPageEnabled:YES];
 //设置域名
 [QTConfigure setCustomDomain:@"您的收数域名" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您应用的appKey" channel:@"App Store"];

关闭某个页面的自动页面采集

/**
 * @brief                   跳过当前页面统计.
 *
 * @param     PageObject    容器对象(自动获取页面时使用,默认手动可填nil)
 * @param     pageName      页面名称(手动设置页面时使用,当设置自动获取页面时可填nil)
 * @warning                 建议在设置页面之前调用此接口,调用后设置的native页面将不发送数据
 *                          
 */
+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

示例:

[UMSpmHybrid skipMe:self pageName:nil];

8.2.2 开启控件点击数据全埋点

说明

自动采集事件是:

  • hook系统sendAction:to:from:forEvent:实现控件执行方法监测

  • 监听addGestureRecognizer:实现所有点击行为

  • hook tableView:didSelectRowAtIndexPath:支持tableView的点击行为

  • hook collectionView:didSelectItemAtIndexPath: 支持collectionView的点击行为

建议在初始化之前调用,默认是关闭

/** 设置是否自动采集点击事件, 默认NO(不自动采集)
 @param value 设置为YES, QT SDK 会将自动采集点击事件
 */
+ (void)setAutoEventEnabled:(BOOL)value;

示例:

 [QTMobClick setAutoEventEnabled:YES];
 //设置域名
 [QTConfigure setCustomDomain:@"您的收数域名" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您应用的appKey" channel:@"App Store"];

支持的控件:

控件名称

备注

UITableView

UICollectionView

UIImageView

有加UITapGestureRecognizer行为的才可以

UILabel

有加UITapGestureRecognizer行为的才可以

UIButton

UISwitch

UIStepper

UISegmentedControl

UISlider

UIPageControl

UITabBarItem

UIBarButtonItem

忽略某个容器的点击事件

/**
 * @abstract
 * 忽略某一页面的点击
 *
 * @param PageObject 对应容器
 */
+(void)ignorePageView:(id)PageObject;

例:

// 该方法支持多次调用,对合集进行忽略    
[QTAutoTrack ignorePageView:self];

忽略特定类型控件点击事件的自动采集

通过 ignoreViewType 方法忽略特定类型控件点击事件的自动采集。

/**
 * @abstract
 * 忽略某一类型的点击
 *
 * @param aClass View 对应的 Class
 */
+(void)ignoreViewType:(Class)aclass;

示例:

// 该方法支持多次调用,对合集进行忽略    
[QTAutoTrack ignoreViewType:[UIButton class]];    
[QTAutoTrack ignoreViewType:[UISwitch class]];

忽略特定控件点击事件的自动采集

通过 UMAnalyticsIgnoreView 方法忽略特定控件点击事件的自动采集。

button.UMAnalyticsIgnoreView=YES;

8.2.3 页面设置自定义信息

页面设置自定义编码

通过实现 -(NSString *)getUMPageName 方法,返回一个自定义编码

-(NSString *)getUMPageName
{
   return @"testPageCode";
}

页面设置自定义属性

通过实现 -(NSDictionary *)getUMPageProperties 方法,给页面设置自定义属性

-(NSDictionary *)getUMPageProperties
{
   return @{@"key1":@"val1",@"key2":@"val2"};
}

页面设置来源(page_referrer)信息

通过实现 -(NSString *) getUMScreenUrl 方法,返回一个自定义来源信息

- (NSString *)getUMScreenUrl {
    return @"um//um/page";
}

8.2.4 设置控件点击事件自定义属性

通过该方法,可以对特定控件设置自定义属性,自定义属性可以设置多个键值对,Key和Value都需要是字符串类型。自定义属性和值会包含在此控件全埋点点击事件数据中。

button.UMAnalyticsViewProperties=@{@"key11":@"val11"};

控件设置Event Code

通过该方法,可以对特定控件设置事件编码

button.UMAnalyticsEventCode=@"abcd123";

9 分享裂变

分享裂变是增长黑客策略的一个关键概念,它依靠用户之间的社交联系来实现信息的相互传递,从而促进新用户的获取。

完成分享裂变的SDK功能集成,您将可以使用QuickTracking平台分享趋势模型,通过分享回流相关指标衡量营销活动的拉新效益。

  1. 支持查看TOP分享用户和不同分享回流层级的分享回流效果指标。

  2. 支持回流指标灵活组合配置,查看最具裂变拉新能力和分享回流转化能力的TOP用户,追踪用户分享裂变链路与分享回流关系,快速定位关键意见消费者。

9.1 获取来源分享参数

/*
 * 来源分享参数获取 API
 * return @{ @"$$_ref_share_id": @"xxxxx", @"$$_ref_share_url": @"xxxxx"}
 **/

+(nullable NSDictionary *)getRefShareParams;

版本要求

iOS sdk 在v1.5.0.PX 版本及以上

功能

当被分享人打开app时,用于获取来源分享id 和来源分享 url 的 API

请求参数

返回参数

默认返回空字典{},如果有值时返回如下:

参数

类型

默认值

含义

备注

$$_ref_share_url

String

""

不包含分享 id 的来源分享 url

$$_ref_share_id

String

""

来源分享 id

调用示例

-(void)onShare {
    __weak typeof(self) weakSelf = self;
    NSDictionary* refShareParams = [QTMobClick getRefShareParams];
    NSString* $$_ref_share_id = [refShareParams objectForKey:@"$sid"];
    
    [QTMobClick requestShareParams:@"https://www.lydaas.com/?utm_source=share" params:@{
        @"title": @"这是一个分享标题",
        @"campaign":@"这是一个分享活动",
        @"shareId": $$_ref_share_id
    } timeout:0 shareResultHandler:^(id  _Nullable result, NSError * _Nullable error) {
        NSLog(@"result === %@", result);
        if (error) {
            NSLog(@"error === %@", error);
        }
        __block NSString *shareId = [(NSDictionary*)result objectForKey:@"$sid"];
        
        NSDictionary *dict = @{
            @"$$_share_id": shareId,
            @"$$_share_url" : @"https://www.lydaas.com/?utm_source=share",
            @"$$_share_title" : @"分享活动A",
            @"$$_share_campaign_id" : @"这是一个自定义分享活动",
            @"$$_share_type" : @"用户自定义分享平台"
        };
        [QTMobClick event:@"$$_share" attributes:dict];
        dispatch_async(dispatch_get_main_queue(), ^{
            UIAlertController *alertController = [UIAlertController 
                alertControllerWithTitle:@"分享参数" message:[NSString 
                stringWithFormat:@"请求分享参数结果如下:\n\n {\n $sid:%@ \n} \n", shareId] 
                preferredStyle:UIAlertControllerStyleAlert];
            // 创建UIAlertAction
            UIAlertAction *confirmAction = [UIAlertAction actionWithTitle:@"知道了" 
                style:UIAlertActionStyleDefault handler:^(UIAlertAction * _Nonnull action) {
                // 点击确定按钮后的处理
                NSLog(@"用户已复制");
                UIPasteboard *pasteboard = [UIPasteboard generalPasteboard];
                pasteboard.string = shareId;
            }];
            [alertController addAction:confirmAction];
            [weakSelf presentViewController:alertController animated:YES completion:nil];
        });
    }];
}

9.2 请求分享参数

#import <QTCommon/MobClick.h>

/*
 * 分享参数获取API
 * @param url, 分享页面的url,必须传入
 * @param params 可能的分享参数,可以为null
 * {
 *   @"title": 分享标题, //可为null,最大长度 4*1024
 *   @"shareId": 来源分享Id, //可为 null
 *   @"campaign": 分享活动, //可为 null,最大长度 4*1024
 *   ... 待扩展
 * }
 * @param timeout 请求超时时间,单位秒,有效值范围:0~10(包含0和10),如果传入0,则使用sdk内部默认值3秒
 * @param shareResultHandler 结果回调对象,必须传入,不能为null
 */

+(void)requestShareParams:(nonnull NSString *)url
                   params:(nonnull NSDictionary *)params
                  timeout:(int)timeout
       shareResultHandler:(nonnull QTShareResultHandler)shareResultHandler;

版本要求

iOS sdk 在v1.5.0.PX 版本及以上

功能

请求用于构建分享链需要的分享id

请求参数

参数

类型

默认值

含义

备注

url

NSString

nil

分享页面的 url

必须传入,不能为 nil

params

NSDictionary

nil

分享参数获取 API 请求参数

  • 可选参数

campaign:分享活动标识。String 类型,默认值为 "",最大长度为 4*1024 个字符

title:分享标题。String类型,默认值为 "",最大长度为 4*1024个长度

shareId:来源分享Id。String 类型,默认值为""

timeout

int

0

接口超时时间

取值范围1~10,单位为秒。 sdk 默认超时时间为3秒

shareResultHandler

QTShareResultHandler

nil

结果回调对象

必须传入,不能为 nil

注:此结果回调上下文为SDK内部网络请求后台工作线程,如果需要在回调方法中操作UI控件,请通过UI线程Handler执行相关操作

返回参数

参数

类型

默认值

含义

备注

result

NSDictionary

nil

分享参数 API 请求结果

包含一个属性

$sid, NSString 类型, 分享id

error

NSError

nil

分享参数 API 请求报错

调用示例

-(void)onShare {
  __weak typeof(self) * weakSelf = self;
 	[QTMobClick requestShareParams:@"https://www.lydaas.com/?utm_source=share" 
   	params:@{
     @"title": @"这是一个分享标题",
     @"campaign":@"这是一个分享活动",
     @"shareId": @"这是一个分享 id"
     } 
   timeout:0 
   shareResultHandler:^(id  _Nullable result, NSError * _Nullable error) {
     NSLog(@"result === %@", result);
     if (error) {
       NSLog(@"error === %@", error);
     }
     __block NSString *shareId = [(NSDictionary*)result objectForKey:@"$sid"]; 
     NSDictionary *dict = @{
       @"$$_share_id": shareId, 
       @"$$_share_url" : @"https://www.lydaas.com/?utm_source=share",
       @"$$_share_title" : @"分享活动A",
       @"$$_share_campaign_id" : @"这是一个自定义分享活动",
       @"$$_share_type" : @"用户自定义分享平台"
     };
     [QTMobClick event:@"$$_share" attributes:dict];
     dispatch_async(dispatch_get_main_queue(), ^{
       UIAlertController *alertController = [UIAlertController alertControllerWithTitle:@"分享参数"
                                             message:[NSString stringWithFormat:
                                             @"请求分享参数结果如下:\n\n {\n $sid:%@ \n} \n", shareId] 
                                             preferredStyle:UIAlertControllerStyleAlert];
       // 创建UIAlertAction
       UIAlertAction *confirmAction = [UIAlertAction actionWithTitle:@"知道了"
                                       style:UIAlertActionStyleDefault
                                       handler:^(UIAlertAction * _Nonnull action) {
                                         // 点击确定按钮后的处理
                                         NSLog(@"用户已复制");
                                         UIPasteboard *pasteboard = [UIPasteboard generalPasteboard];
                                         pasteboard.string = shareId;                                                     
                                       }];
       [alertController addAction:confirmAction];
       [weakSelf presentViewController:alertController animated:YES completion:nil];
     });
   }];
}

9.3 上报分享事件

通过预置事件编码 $$_share 上报分享事件

示例:

[QTMobClick requestShareParams:@"https://www.lydaas.com/?utm_source=share"
                        params:@{
    @"title": @"这是一个分享标题",
    @"campaign":@"这是一个分享活动",
    @"shareId": @"这是一个分享 id"
}
                        timeout:0
            shareResultHandler:^(id  _Nullable result, NSError * _Nullable error) {
    NSLog(@"result === %@", result);
    if (error) {
        NSLog(@"error === %@", error);
    }
    __block NSString *shareId = [(NSDictionary*)result objectForKey:@"$sid"];
    NSDictionary *dict = @{
        @"$$_share_id": shareId,
        @"$$_share_url" : @"https://www.lydaas.com/?utm_source=share",
        @"$$_share_title" : @"分享活动A",
        @"$$_share_campaign_id" : @"这是一个自定义分享活动",
        @"$$_share_type" : @"用户自定义分享平台"
    };
    [QTMobClick event:@"$$_share" attributes:dict];   
}];

请注意:唤起的链接需要携带key为"$sid",value为分享Id的参数,如:https://example.aliyun.com/path/to/content?$sid=123456"