1. Integration

1.1. Pod Integration

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

CODE

1.2. Source Code Integration

Please refer to the official website source code integration. The exposure module is already included in the source code. Refer to the link: https://manual.sensorsdata.cn/sa/latest/sdk-ios-7538614.html#SDK Integration (iOS)-Integrate Tracking SDK

Version Requirement

Requires SensorsAnalyticsSDK SDK v4.4.6 or above

2. Usage

Before using the Sensors Data exposure function, it is recommended to learn more about the introduction of exposure in Sensors Data: Exposure Tracking

2.1. Exposure Condition Configuration Parameters

The SDK provides SAExposureConfig to set exposure conditions. The specific parameter descriptions are as follows:

Parameter

Type

Description

areaRate

CGFloat

The visible ratio of exposure, valid range is 0~1,

The default value is 0, which means the element only needs to be partially visible to meet the visibility condition
The maximum value is 1, which means that the element needs to be fully exposed to meet the visible ratio condition

stayDuration

NSTimeInterval

Effective stay duration, measured in seconds

The default value is 0, which means that the element only needs to meet the visible ratio to satisfy the effective stay duration

repeated

BOOL

Whether to allow collecting repeated exposures

The default value is YES, which means that repeated exposures are allowed

2.2. Exposure condition settings

Initialize an exposure configuration

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

CODE

The SDK provides global exposure configuration settings

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

CODE

Or set individually for a specific view element

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

CODE

Note:

The global exposure setting has a default value, wherein areaRate = 0, stayDuration = 0, repeated = YES
If no configuration item is passed when marking a view element, the global exposure configuration will be used
If a configuration item is passed when marking a view element, the custom configuration passed will be used
Different view elements can use different exposure configurations, and the exposure configuration corresponds to the configuration passed when marking the view

2.3. Exposure element tagging

2.3.1. Element tagging related classes and interface explanations

SDK provides the SAExposureData class and the addExposureView interface to mark the exposure of an element. The relevant instructions are as follows:

SAExposureData

Parameter	Type	Description
event	NSString	The event name triggered when the element is exposed
properties	NSDictionary	The properties of the event triggered when the element is exposed
exposureIdentifier	NSString	The exposure identifier used to differentiate elements and enable precise exposure in certain scenarios, such as cell reuse in UITableView / UICollectionView
config	SAExposureConfig	Exposure condition configuration

addExposureView

Parameter	Type	Description
view	UIView	The element object that needs to be exposed
data	SAExposureData	The exposure data passed in when marking the element, including event name, properties, and exposure condition configuration

2.3.2. Marking for normal view elements

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];

CODE

2.3.3. Marking for list elements

Take UITableView as an example

2.3.3.1. Marking for a single row

- (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; }

CODE

Note: If you mark a row without using exposure flag, it will cause inaccurate exposure data collection. Only relying on indexPath or cell is not enough to accurately determine whether the current cell is the element you want to mark.

2.3.3.2. Marking for all rows

- (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; }

CODE

2.3.4. Removing the element mark

When we don't want to collect the exposure of a certain element, we can use the removeExposureView interface provided by the SDK. The interface is described as follows:

Parameter	Type	Description
view	UIView	The object element that needs to be removed from exposure
identifier	NSString	The identifier of the exposed element. If you need to remove a specific exposed element accurately, please pass in the identifier when marking. It can be omitted under normal circumstances

以下是示例代码

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

CODE

2.4. Exposure callback

The SDK provides an exposure listening protocol interface from version 4.5.10, which can be set through the exposureListener in SAExposureData. The protocol is as follows:

@protocol SAExposureListener <NSObject> @optional - (BOOL)shouldExpose:(UIView *)view withData:(SAExposureData *)data; - (void)didExpose:(UIView *)view withData:(SAExposureData *)data; @end

CODE

The parameter description is as follows:

Parameter	Type	Description
view	UIView	The element being exposed
data	SAExposureData	The exposure data passed in when marking the element, including event name, properties, and exposure condition configuration

Example code is as follows:

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 { //可以根据实际业务需求，在触发曝光后，进行一些业务操作 }

CODE

2.5. Update exposure property for a specific element

SDK provides an interface to update the property of a specific exposed element starting from version 4.5.10. updateExposure: withProperties:. The interface is described as follows:

Parameter	Type	Description
view	UIView	The exposed element to be updated
properties	NSDictionary	The properties to be updated

Example code is as follows:

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

CODE