1. SDK Integration

Please refer to the integration document (Android).

Version Requirement

Android SDK v6.5.2 and above

2. Usage

Before using the Sensors Data exposure function, it is recommended to first understand the introduction to the Sensors Data exposure function: Exposure Collection

2.1. Exposure Condition Setting

Initialize an exposure configuration

SAExposureConfig exposureConfig = new SAExposureConfig(areaRate, stayDuration, repeated);

SAExposureConfig details are as follows:

Note: The exposure tracking event can only be triggered when all three exposure configurations areaRate, stayDuration, and repeated are met.

//当我们设置元素完全曝光，有效停留时长 1s ，支持重复曝光 SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true);

The SDK provides global exposure configuration settings

String SA_SERVER_URL = "数据接收地址"; // 初始化 SDK 配置 SAConfigOptions configOptions = new SAConfigOptions(SA_SERVER_URL); // 初始化曝光模块配置 configOptions.setExposureConfig(exposureConfig);

The SDK sets exposure configuration for a specific view element separately

View view = findViewById(R.id.resourceID); String event = "曝光事件名称"; JSONObject properties = new JSONObject(); try { properties.put("曝光事件属性 key", "曝光事件属性 value"); } catch (JSONException e) { e.printStackTrace(); } SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true); SAExposureData exposureData = new SAExposureData(event, properties, exposureConfig); SensorsDataAPI.sharedInstance().addExposureView(view, exposureData); //标记视图元素

SAExposureData detailed parameters are as follows:

Parameter details for addExposureView are as follows:

Note:

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

3. Exposure element tag

3.1. Normal view element tag

View view = findViewById(R.id.resourceID); String event = "曝光事件名称"; JSONObject properties = new JSONObject(); try { properties.put("曝光事件属性 key", "曝光事件属性 value"); } catch (JSONException e) { e.printStackTrace(); } SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true); SAExposureData exposureData = new SAExposureData(event, properties, exposureConfig); SensorsDataAPI.sharedInstance().addExposureView(view, exposureData); 

3.2. List element tag

When the list is exposed, the list elements can be reused during the rendering process, so the list elements need to be uniquely identified by setting the exposureIdentifier. This can generally be done by using the SAExposureData as shown below:

SAExposureData exposureData = new SAExposureData("exposureName", null, "11",exposureConfig);

SAExposureData detailed parameters are as follows:

SAExposureConfig

Note: When an element (view) is set with a unique identifier (exposureIdentifier), the exposure element is identified by the unique identifier. Therefore, it is not recommended to set the same unique identifier for different elements on the same page. It is only recommended to use element unique identifier when using a list to avoid inaccurate collection caused by list reuse.

Below is an example using RecyclerView, and the unique identifier for the element is generally marked based on the position of the list:

3.2.1. Mark all rows

public void onBindViewHolder(@NonNull ViewHolder holder, final int position) { View view = holder.xxxx;     SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true); SAExposureData exposureData = new SAExposureData("exposureName", null, "曝光标识", exposureConfig);////曝光标识用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的数据源中的唯一标识来处理     SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);//添加曝光元素（view）到曝光列表 }

3.2.2. Mark a single row

When marking a specific row or column in a list instead of all rows or columns, you need to mark all elements through setExposureIdentifier, and then mark the elements of the rows or columns that need exposure through addExposureView.

//进行标记所有的元素曝光标识，用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的数据源中的唯一标识来处理 SensorsDataAPI.sharedInstance().setExposureIdentifier(view, "曝光标识");

The detailed parameters of setExposureIdentifier are as follows:

exposureIdentifier

public void onBindViewHolder(@NonNull ViewHolder holder, final int position) { View view = holder.xxxx; SensorsDataAPI.sharedInstance().setExposureIdentifier(view, String.valueOf(position));//曝光标识用于区分列表元素的特殊场景，比如列表元素复用、列表元素位置变更（刷新、删除、添加等），建议客户使用列表元素的位置作为唯一标识来处理 //只采集列表 position 为 1 的曝光元素的曝光事件 	if(position==1){ SAExposureConfig exposureConfig = new SAExposureConfig(1.0f, 1, true); SAExposureData exposureData = new SAExposureData("exposureName", null, "曝光标识",exposureConfig);//此处的曝光标识，建议客户使用列表元素的数据源中的唯一标识来处理     SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);//添加曝光元素（view）到曝光列表 } }

Note: If marking a row or column, it is necessary to set the exposure identifier setExposureIdentifier to ensure accurate exposure data collection. Simply relying on the position alone cannot accurately determine if the current position is the desired element. Additionally, the unique identifier for the view marked by setExposureIdentifier and addExposureView must be the same.

3.3. Remove Element Marking

If we don't want to collect the exposure of a certain element, we can use the removeExposureView API provided by the SDK, which includes the following two interfaces:

//方法一： View view = findViewById(R.id.resourceID); SensorsDataAPI.sharedInstance().removeExposureView(view); //方法二： View view = findViewById(R.id.resourceID); SensorsDataAPI.sharedInstance().removeExposureView(view,"aaa");

The detailed parameters for removeExposureView are as follows:

exposureIdentifier

Note: When using removeExposureView with the exposureIdentifier parameter, both the view and the exposureIdentifier must be exactly the same as the information added to the exposure list in order to remove it.

3.4. Exposure Callback

The SDK provides an exposure monitoring protocol interface from version 6.6.9, which can be set through SAExposureData's exposureListener. The interface is described as follows:

saExposureData.setExposureListener(SAExposureListener saExposureListener)

SAExposureListener details are as follows:

public interface SAExposureListener { /** * 返回对应 View 是否曝光 * * @param view View * @param exposureData View 对应数据 * @return true：曝光，false：不曝光 */ boolean shouldExposure(View view, SAExposureData exposureData); /** * 曝光完成回调 * * @param view View * @param exposureData 曝光数据 */ void didExposure(View view, SAExposureData exposureData); }

The parameter details are as follows:

Note: shouldExposure and didExposure callbacks are executed in the main thread, so time-consuming operations are prohibited.

Code usage example:

SAExposureData exposureData = new SAExposureData("expose"); exposureData.setExposureListener(new SAExposureListener() { 	@Override 	public boolean shouldExposure(View view, SAExposureData exposureData) { 		//可以根据实际业务来返回 true 或者 false，这里影响当前曝光监听者的所有曝光事件，需谨慎使用 		if (不需要曝光的条件) { 			return false; 		} 		return true; 	} 	@Override 	public void didExposure(View view, SAExposureData exposureData) { 		//可以根据实际业务需求，在触发曝光后，进行一些业务操作 	} }); SensorsDataAPI.sharedInstance().addExposureView(view, exposureData);

3.5. Update the exposure properties of an element

From version 6.6.9, the SDK provides a protocol interface for exposure listening, which can change the properties of exposed elements through updateExposureProperties.

SensorsDataAPI.sharedInstance().updateExposureProperties(view, properties);