曝光采集（iOS）

集成

pod 集成

// Exposure 为 曝光模块，必须要包含，Core 为 SDK 默认集成的模块，至于其他 subspecs，按需集成
pod 'SensorsAnalyticsSDK', :subspecs =>  ['Core', 'Exposure']

源码集成

请参考官网源码集成，曝光模块已经在源码中，参考文档：集成文档（iOS）

注意

SDK 版本需要 >= 4.4.6

使用

在使用神策曝光功能之前，建议先了解下神策曝光的相关介绍：曝光采集

曝光条件配置参数

SDK 提供 SAExposureConfig 来设置曝光条件，具体参数说明如下：

参数

类型

描述

areaRate

CGFloat

曝光的可见比例，有效值范围 0~1，

默认值为 0，代表元素只要露出就满足可见比例条件
最大值为 1，代表元素需要完全露出才可满足可见比例条件

stayDuration

NSTimeInterval

有效停留时长，单位为秒

默认值为 0，代表元素只要满足了可见比例，有效停留时长就可满足

repeated

BOOL

是否允许采集重复曝光

默认值为 YES，及允许采集重复曝光

曝光条件设置

初始化一个曝光配置

SAExposureConfig *exposureConfig = [[SAExposureConfig alloc] initWithAreaRate:<#areaRate#> stayDuration:<#duration#> repeated:<#isRepeated#>];

SDK 提供全局设置曝光配置

SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#serverURL#> launchOptions:launchOptions];
options.exposureConfig = exposureConfig;

或者对某个视图元素单独设置

SAExposureData *exposureData = [[SAExposureData alloc] initWithEvent:<#event#> properties:<#properties#> config:exposureConfig];
[SensorsAnalyticsSDK.sharedInstance addExposureView:<#view#> exposureData]; //标记视图元素

注意：

全局的曝光设置有一个默认值，及 areaRate = 0，stayDuration = 0，repeated = YES
标记视图元素时，如果不传入配置项，则会使用全局曝光配置
标记视图元素时，如果传入配置项，则会使用传入的自定义配置
不同的视图元素可以使用不同的曝光配置，曝光配置和标记视图时传入的配置对应

曝光元素标记

元素标记相关类和接口说明

SDK 提供 SAExposureData 类和接口 addExposureView 来标记某个元素的曝光，相关的说明如下

SAExposureData

参数	类型	描述
event	NSString	元素曝光时触发的事件名
properties	NSDictionary	元素曝光时触发的事件的属性
exposureIdentifier	NSString	曝光标识，用于某些场景下区分元素和精准曝光，例如 UITableView / UICollectionView下的 cell 复用场景
config	SAExposureConfig	曝光条件配置

addExposureView

参数	类型	描述
view	UIView	需要被曝光的元素对象
data	SAExposureData	标记元素时传入的曝光数据，包含事件名、属性、曝光条件配置等

普通视图元素标记

以 UIButton 添加曝光示例如下：

UIButton *button = [[UIButton alloc] initWithFrame:<#frame#>];
SAExposureConfig *exposureConfig = [[SAExposureConfig alloc] initWithAreaRate:<#areaRate#> stayDuration:<#duration#> repeated:<#isRepeated#>];
SAExposureData *exposureData = [[SAExposureData alloc] initWithEvent:<#event#> properties:<#properties#> config:exposureConfig];
[[SensorsAnalyticsSDK sharedInstance] addExposureView:button withData:exposureData];

列表元素标记

以 UITableView 为例

标记单个行

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
   UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"reuseIdentifier"];
   if (!cell) {
      cell = ....;
   }
   cell.exposureIdentifier = <#曝光标识#>;   //曝光标识用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的数据源中的唯一标识来处理
   if (indexPath.row == 1) {                // if 判断条件只是举例，建议根据自身业务逻辑来处理，强烈不建议使用 row 来判断
        SAExposureConfig *exposureConfig  = [[SAExposureConfig alloc] initWithAreaRate:<#areaRate#> stayDuration:<#duration#> repeated:<#repeated#>];
        SAExposureData *exposureData = [[SAExposureData alloc] initWithEvent:<#event#> properties:<#properties#> exposureIdentifier:<#曝光标识#> config:exposureConfig]; // 此处的曝光标识，需要传入需要标记的列表元素的唯一标识
        [[SensorsAnalyticsSDK sharedInstance] addExposureView:cell withData:exposureData];
    }
    return cell;
}

注意：如果标记某一行时，不使用曝光标识，会导致曝光数据采集不准，单纯靠 indexPath 或者 cell 是无法准确判定当前 cell 是否是想要标记的元素。

标记所有行

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
   UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"reuseIdentifier"];
   if (!cell) {
      cell = ....;
   }
   SAExposureConfig *exposureConfig  = [[SAExposureConfig alloc] initWithAreaRate:<#areaRate#> stayDuration:<#duration#> repeated:<#repeated#>];
   SAExposureData *exposureData = [[SAExposureData alloc] initWithEvent:<#event#> properties:<#properties#> config:exposureConfig];
   [[SensorsAnalyticsSDK sharedInstance] addExposureView:cell withData:exposureData];
    return cell;
}

移除元素标记

当我们不想采集某个元素的曝光时，可以使用 SDK 提供的移除标记接口 removeExposureView，接口说明如下

参数	类型	描述
view	UIView	需要移除曝光的元素对象
identifier	NSString	曝光元素标识，如果需要精准的移除某个曝光元素，请传入标记时传入的标识，正常情况下可以不用传入

示例代码如下

[[SensorsAnalyticsSDK sharedInstance] removeExposureView:<#需要移除曝光采集的元素#> withExposureIdentifier:nil];

曝光回调

SDK 从 4.5.10 版本提供了一个曝光监听的协议接口，可通过 SAExposureData 中的 exposureListener 来设置，协议内容如下：

@protocol SAExposureListener 

@optional
- (BOOL)shouldExpose:(UIView *)view withData:(SAExposureData *)data;
- (void)didExpose:(UIView *)view withData:(SAExposureData *)data;

@end

其中参数说明如下：

参数	类型	描述
view	UIView	曝光的元素
data	SAExposureData	标记元素时传入的曝光数据，包含事件名、属性、曝光条件配置等

示例代码如下：

SAExposureConfig *exposureConfig  = [[SAExposureConfig alloc] initWithAreaRate:<#areaRate#> stayDuration:<#duration#> repeated:<#repeated#>];
SAExposureData *exposureData = [[SAExposureData alloc] initWithEvent:<#event#> properties:<#properties#> config:exposureConfig];
exposureData.exposureListener = self;

//是否触发某个元素的曝光回调
- (BOOL)shouldExpose:(UIView *)view withData:(SAExposureData *)data {
    //可以根据实际业务来返回 YES 或者 NO，这里影响当前曝光监听者的所有曝光事件，需谨慎使用
    if (不需要曝光的条件) {
        return NO;
    }
    return YES;
}

//已经触发某个曝光元素的回调
- (void)didExpose:(UIView *)view withData:(SAExposureData *)data {
    //可以根据实际业务需求，在触发曝光后，进行一些业务操作
}

更新某个元素的曝光属性

SDK 从 4.5.10 版本提供了更新某个曝光元素的属性的接口 updateExposure: withProperties:，接口说明如下:

参数	类型	描述
view	UIView	需要更新的曝光元素
properties	NSDictionary	需要更新的属性

示例代码如下：

//view 为需要更新的元素，properties 为需要更新的属性，为字典类型
[SensorsAnalyticsSDK.sharedInstance updateExposure:view withProperties:properties];