目录

HiAnalyticsInstance

Class Info

com.huawei.hms.analytics.HiAnalyticsInstance

Analytics单例类，提供上报用户行为数据的公共方法。

Public Method Summary

Qualifier and Type

Method Name and Description

void

setAnalyticsEnabled(final boolean enabled)

是否打开埋点采集能力。

void

setAutoCollectionEnabled(boolean isEnabled)

注意：

该接口已废弃。

void

setUserId(String id)

设置用户ID。

void

setUserProfile(String name, String value)

设置用户属性。

void

setPushToken(String token)

设置Push Token，通过Push Kit获取。

void

setMinActivitySessions(final long milliseconds)

设置App在后台运行时刷新Session的最短时间间隔。

void

setSessionDuration(final long milliseconds)

设置Session超时时长。

void

setCurrentActivity(Activity activity, String activityName, String activityClassOverride)

注意：

该接口已废弃，请使用pageStart(String pageName, String pageClassOverride)和pageEnd(String pageName)接口。

void

onEvent(String eventId, Bundle params)

记录事件。

void

clearCachedData()

清除本地缓存的所有采集数据。

Task<String>

getAAID()

获取应用的匿名设备标识。

void

regHmsSvcEvent()

注意：

该接口已废弃。

void

unRegHmsSvcEvent()

注意：

该接口已废弃。

Map<String, String>

getUserProfiles(boolean preDefined)

获取自采集或者自定义的用户属性。

void

pageStart(String pageName, String pageClassOverride)

自定义进入页面事件。

void

pageEnd(String pageName)

自定义退出页面事件。

void

setReportPolicies(Set<ReportPolicy> policies)

设置自动上报的策略。

void

setRestrictionEnabled(boolean isEnabled)

设置是否限制数据分析能力。

boolean

isRestrictionEnabled()

获取当前限制数据分析开关的状态。

void

setCollectAdsIdEnabled(boolean isEnabled)

设置是否开启采集广告标识符。

void

setRestrictionShared(boolean shared)

设置是否限制数据共享。

boolean

isRestrictionShared()

获取限制数据共享开关的状态。

void

addDefaultEventParams(final Bundle params)

添加默认事件参数。

void

setWXOpenId(String wxOpenId)

设置微信openId。

void

setWXUnionId(String wxUnionId)

设置微信unionId。

void

setWXAppId(String wxAppId)

设置微信appId。

void

setChannel(String channel)

设置应用安装来源。

void

setPushTokenCollectionEnabled(boolean enabled)

设置是否允许采集pushtoken。

void

setPropertyCollection(String property, boolean enabled)

设置是否允许采集系统属性。

void

setCustomReferrer(String customReferrer)

设置自定义Referrer。

void

onNewIntent(Intent intent)

同步新的Intent，用于获取营销信息。

String

getDataUploadSiteInfo()

获取当前数据上报的数据处理位置。

Public Methods

[h2]setAnalyticsEnabled

Method

public void setAnalyticsEnabled(final boolean enabled)

是否打开埋点采集能力。关闭后将不再记录任何数据，且不分析数据。

说明：

Parameters

Name

Description

enabled

是否打开埋点采集开关。默认值为true，表示打开埋点采集。

  • true：打开
  • false：关闭

Sample code：

SDK默认打开采集数据，您可参考以下示例代码，关闭埋点采集能力。

“Java”
HiAnalyticsInstance instance = HiAnalytics.getInstance(context);
instance.setAnalyticsEnabled(false);
“Kotlin”
val instance = HiAnalytics.getInstance(context)
instance.setAnalyticsEnabled(false)

[h2]setAutoCollectionEnabled

该接口已废弃。

Method

public void setAutoCollectionEnabled(boolean isEnabled)

初始化时自动开启采集系统事件的开关。

Parameters

Name

Description

isEnabled

是否自动采集事件。默认打开。

  • true：打开
  • false：关闭

[h2]setUserId

Method

public void setUserId(String id)

设置用户ID。

调用setUserId()接口时，如果旧id不为空字符串且和新id不同，会重新生成新的Session会话。若您不希望使用setUserId标识用户（如用户退出时），必须将id设为null。

SDK不会保存您的用户ID，建议您在每次应用启动后设置用户ID。

Parameters

Name

Description

id

匿名化用户标识，在华为分析服务侧通过此标识关联用户数据。只有您可以使用该标识符追溯到具体用户，分析系统无法使用您设置的id追溯到具体用户。

非空，长度不超过256字符。

说明：

设置id时，需要遵守分析服务协议，避免使用能标识个人身份信息的原始id，建议使用随机化的id。

[h2]setUserProfile

Method

public void setUserProfile(String name, String value)

设置用户属性。用户属性值将在整个应用程序生命周期和会话期间保持不变。最多支持25个用户属性名称，如果后面设置属性有重复的name，则刷新value值。

Parameters

Name

Description

name

用户属性的标识符。非空，由数字、字母、下划线组成，必须以字母开头，长度不超过256字符。

value

属性值。长度不超过256字符。
  • value可以设置为null，通过传null来实现删除对应的用户属性。
  • 如果您删除或新增属性，需要在端侧和云侧同步修改，并通过设置的属性name进行关联。

[h2]setPushToken

Method

public void setPushToken(String token)

设置Push Token。您可以在Push Kit获取到Push Token后，通过此接口保存Push Token，以便支撑您使用Analytics Kit定义的受众创建HCM通知任务。

说明：

6.3.0.301及以上版本，中国大陆设置华为Push Token方式如下：

  • EMUI 10.0以下版本，通过此接口设置Push Token。
  • EMUI 10.0及以上版本，已支持自动获取Push Token，您无需调用此接口。

Parameters

Name

Description

token

Push Token。非空，长度不超过256字符。

[h2]setMinActivitySessions

Method

public void setMinActivitySessions(final long milliseconds)

设置App在后台运行时刷新Session的最短时间间隔。当App在后台运行，若在后台持续时间超过此接口设置的阈值，再次进入前台时，将生成一个新的会话。

Parameters

Name

Description

milliseconds

刷新Session的最短时间间隔。单位：毫秒。

取值范围：最小值5秒，最大值5小时。如果设置的值小于最小则取最小，大于最大则取最大。默认30000毫秒（30秒）。

[h2]setSessionDuration

Method

public void setSessionDuration(final long milliseconds)

设置Session超时时长。App一直在前台运行，当两个相邻事件的时间间隔超过此接口设置的阈值时，将生成一个新的会话。

Parameters

Name

Description

milliseconds

Session超时时长。单位：毫秒。

取值范围：最小值5秒，最大值5小时。如果设置的值超过给定范围则取边界值。默认为1800000毫秒（30分钟）。

[h2]setCurrentActivity

该接口已废弃。请使用pageStart和pageEnd接口，支持非Activity页面完整的进入和退出事件采集。

Method

public void setCurrentActivity(Activity activity, String activityName, String activityClassOverride)

  • Analytics Kit会自动采集$EnterScreen和$ExitScreen事件中的$CurActivityName参数。若您需要覆盖自动采集的$EnterScreen和$ExitScreen事件，您可在Activity的onResume中调用此接口，并指定页面名称（activityName，必选）和类名（activityClassOverride，可选，若为null或空，Analytics Kit将根据传入的activity获取类名）。
  • 您也可以调用该接口记录非Activity的页面事件（如Fragment、自定义View等），并指定相关页面名称（activityName，必选）。

Parameters

Name

Description

activity

当前活动Activity。

activityName

当前活动页面名称。非空，长度不超过256字符。

activityClassOverride

页面类名，可选，若设置为null或空，则会使用当前活动Activity的类名；长度不超过256字符。

[h2]onEvent

Method

public void onEvent(String eventId, Bundle params)

记录事件。

Parameters

Name

Description

eventId

事件标识符。非空，由数字、字母、下划线组成，不能以数字开头，不能包含空格，长度不超过256字符，不能使用自动采集事件ID。

例如：“event_description10”。

params

事件携带的信息。Bundle内键值对不超过2048个，同时大小不超过204800个字符。

说明：
  • Bundle内value支持的类型：Bundle、ArrayList、String、int、long、double、boolean、float、char、byte、short。Bundle内key值由数字、字母、下划线组成，不能以数字开头。
  • 最外层Bundle只能内嵌一个Bundle，一个ArrayList对象，内嵌的Bundle参数只支持基本数据类型，ArrayList的元素可以是Bundle或者基本数据类型，ArrayList中的Bundle也只能嵌套基本类型，ArrayList的size最多支持50个。

[h2]clearCachedData

Method

public void clearCachedData()

清除本地缓存的所有采集数据，包括发送失败的缓存数据。

通过以下接口设置的数据将被清理：

说明：

调用此接口将重置AAID，从6.0.0版本开始userId也会被重置。

[h2]getAAID

Method

public Task<String> getAAID()

获取应用的匿名设备标识。

Returns

Type

Description

Task<String>

获取AAID（Anonymous Application ID）的Task。Task类的定义请参见Task<TResult>。

[h2]regHmsSvcEvent

该接口已废弃。

Method

public void regHmsSvcEvent()

SDK已实现自动绑定Analytics Kit App服务，您无需额外调用该接口。

[h2]unRegHmsSvcEvent

该接口已废弃。

Method

public void unRegHmsSvcEvent()

Analytics SDK已实现自动解绑Analytics Kit App服务，您无需额外调用该接口。

[h2]getUserProfiles

Method

public Map<String, String> getUserProfiles(boolean preDefined)

获取自采集或者自定义的用户属性。

说明：

此接口获取不到自动采集用户属性中的AAID、广告标识符、Push Token。

Parameters

Name

Description

preDefined

获取自采集用户属性或者自定义用户属性。

  • true：获取自采集用户属性。
  • false：获取自定义用户属性。

Returns

Type

Description

Map<String, String>

自采集或者自定义的用户属性。

[h2]pageStart

Method

public void pageStart(String pageName, String pageClassOverride)

自定义进入页面事件，只在非Activity的页面调用，需要在调用本接口后调用pageEnd接口配对使用。

Activity页面无需调用，Activity页面会自动采集。如果在Activity页面调用，会导致页面进出事件统计不准确。

Parameters

Name

Description

pageName

当前页面名称，长度不超过256字符，不可为空。

pageClassOverride

当前页面类名，长度不超过256字符，不可为空。

[h2]pageEnd

Method

public void pageEnd(String pageName)

自定义退出页面事件，只在非Activity的页面调用，需要在调用本接口前先调用pageStart接口配对使用。

Activity页面无需调用，Activity页面会自动采集。如果在Activity页面调用，会导致页面进出事件统计不准确。

说明：

请确保在自定义页面（如Fragment）进入Activity页面时，该自定义页面为最后一个调用pageEnd接口的页面。

Parameters

Name

Description

pageName

当前结束的页面名称，长度不超过256字符，不可为空，需要和对应pageStart内传入的pageName相同。

[h2]setReportPolicies

Method

public void setReportPolicies(Set<ReportPolicy> policies)

设置自动上报的策略。

Parameters

Name

Description

policies

支持四种上报策略，可以设置多个策略同时存在。

  • ON_APP_LAUNCH_POLICY：应用启动上报策略，选择该策略时会立即上报一次，此后每次应用启动时上报一次。
  • ON_MOVE_BACKGROUND_POLICY：应用切后台（包括应用退出）上报策略。
  • ON_SCHEDULED_TIME_POLICY：定时上报策略，根据指定的间隔时间轮循上报事件，取值范围为[60, 1800]秒（默认60秒），如果设置的值超过给定范围则取边界值。
  • ON_CACHE_THRESHOLD_POLICY：阈值上报策略，缓存事件条数达到阈值时上报事件，取值范围为[30, 1000]条（默认30条），如果设置的值超过给定范围则取边界值。
  • 以上上报策略仅在非调试模式下生效。
  • 应用切后台上报策略和阈值上报策略为必选策略，无论设置什么策略，这两个策略都会生效，但是可以改变阈值上报策略的阈值。
  • 多次调用设置上报策略的接口，会刷新上报策略，仅最后一次设置的策略生效，请谨慎多次调用。
  • 当策略满足触发事件上报时，如果没有网络，则会将事件缓存在本地，等待下次条件满足继续上报。
  • 上报策略持久化保存。

Sample code：

您可以参考以下示例代码，设置应用切后台上报策略和定时上报策略。

“Java”
// 创建应用切后台上报策略
ReportPolicy moveBackgroundPolicy = ReportPolicy.ON_MOVE_BACKGROUND_POLICY;
// 创建定时上报策略
ReportPolicy scheduledTimePolicy = ReportPolicy.ON_SCHEDULED_TIME_POLICY;
// 设置定时上报时间周期为600秒
scheduledTimePolicy.setThreshold(600);
Set<ReportPolicy> reportPolicies = new HashSet<>();
// 添加定时上报策略和应用切后台上报策略
reportPolicies.add(scheduledTimePolicy);
reportPolicies.add(moveBackgroundPolicy);
// 设置应用切后台上报策略和定时上报策略
instance.setReportPolicies(reportPolicies);
“Kotlin”
// 创建应用切后台上报策略
val moveBackgroundPolicy = ReportPolicy.ON_MOVE_BACKGROUND_POLICY
// 创建定时上报策略
val scheduledTimePolicy = ReportPolicy.ON_SCHEDULED_TIME_POLICY
// 设置定时上报时间周期为600秒
scheduledTimePolicy.threshold = 600
val reportPolicies = HashSet<ReportPolicy>()
// 添加定时上报策略和应用切后台上报策略
reportPolicies.add(scheduledTimePolicy)
reportPolicies.add(moveBackgroundPolicy)
// 设置应用切后台上报策略和定时上报策略
instance.setReportPolicies(reportPolicies)

[h2]setRestrictionEnabled

Method

public void setRestrictionEnabled(boolean isEnabled)

设置是否限制数据分析能力。限制分析开关默认值为false，即默认开启数据分析能力。

说明：
  • 此接口设置为true时，setRestrictionShared中的值也会被设置为true，即自动限制数据共享。
  • 此接口设置为false时，若开启数据共享，需要手动设置setRestrictionShared为false。

Parameters

Name

Description

isEnabled

打开或关闭数据分析能力。默认值为false，即打开数据分析能力。

  • true：关闭
  • false：打开

Sample code：

“Java”
// 限制数据分析，同时也会自动限制数据共享
HiAnalyticsInstance instance = HiAnalytics.getInstance(context);
instance.setRestrictionEnabled(true);

// 开启数据分析
instance.setRestrictionEnabled(false);

// 开启数据共享
instance.setRestrictionShared (false);
“Kotlin”
// 限制数据分析，同时也会自动限制数据共享
val instance = HiAnalytics.getInstance(context)
instance.setRestrictionEnabled(true)

// 开启数据分析
instance.setRestrictionEnabled(false)

// 开启数据共享
instance.setRestrictionShared (false)

[h2]isRestrictionEnabled

Method

public boolean isRestrictionEnabled()

获取当前限制数据分析开关的状态。

Returns

Type

Description

boolean

获取当前限制数据分析开关的状态。

  • true：当前数据分析是关闭状态。
  • false：当前数据分析是打开状态。

[h2]setCollectAdsIdEnabled

Method

public void setCollectAdsIdEnabled(boolean isEnabled)

设置是否允许采集广告标识符。

说明：
  • 是否允许采集广告标识符也可以通过在“AndroidManifest.xml”文件中添加meta-data参数，设置analyticskit_adsid_collection_enabled的值来实现。详情请参见（可选）配置“AndroidManifest.xml”文件。
  • 通过该接口设置的值，优先级高于通过“AndroidManifest.xml”文件设置的值。

Parameters

Type

Description

isEnabled

是否允许采集广告标识符。默认值为true，即允许采集。

  • true：允许
  • false：不允许

[h2]setRestrictionShared

Method

public void setRestrictionShared(boolean shared)

设置是否限制数据共享能力。限制数据共享开关默认值为false，即默认开启数据共享能力。

说明：

仅中国大陆可用，非中国大陆调用无效。

Parameters

Name

Description

shared

打开或关闭数据共享能力。默认值为false，即打开数据共享能力。

  • true：关闭
  • false：打开

[h2]isRestrictionShared

Method

public boolean isRestrictionShared()

获取当前限制数据共享开关状态。

说明：

仅中国大陆可用，非中国大陆调用无效。

Returns

Type

Description

boolean

获取当前限制数据共享开关状态。

  • true：当前数据共享是关闭状态。
  • false：当前数据共享是打开状态。

[h2]addDefaultEventParams

Method

public void addDefaultEventParams(final Bundle params)

添加默认事件参数，默认事件参数将被添加到除自动采集事件之外的所有事件中，默认事件参数与事件参数同名时，使用事件参数。

Parameters

Name

Description

params

默认事件参数。

参数最多支持100个键值对，每个键值对中key的长度不能超过256个字符，且只能由数字、字母、下划线组成，不能以数字开头；value长度不能超过256个字符，value只支持String、int、long、double、boolean、float、char、byte、short。

说明：
  • 如果传入的params为null，将清除所有缓存的默认事件参数；如果传入的键值对中value为null，将删除对应的默认事件参数；如果传入的键值对中key已存在，将更新对应的默认事件参数。
  • 默认事件参数的个数和大小会被onEvent计入，请注意参数的使用限制。

[h2]setWXOpenId

Method

public void setWXOpenId(String wxOpenId)

设置微信openId。

若您不希望使用setWXOpenId标识用户（如用户退出时），必须将wxOpenId设为null。

Parameters

Name

Description

wxOpenId

非空，长度不超过256字符。

说明：
  • 如果参数非法，SDK将会重置wxOpenId为空字符串。
  • 如果传入的wxOpenId为null，将清除设置的微信openId。

[h2]setWXUnionId

Method

public void setWXUnionId(String wxUnionId)

设置微信unionId。

若您不希望使用setWXUnionId标识用户（如用户退出时），必须将wxUnionId设为null。

Parameters

Name

Description

wxUnionId

非空，长度不超过256字符。

说明：
  • 如果参数非法，SDK将会重置wxUnionId为空字符串。
  • 如果传入的wxUnionId为null，将清除设置的微信unionId。

[h2]setWXAppId

Method

public void setWXAppId(String wxAppId)

设置微信AppId。

Parameters

Name

Description

wxAppId

非空，长度不超过256字符。

说明：
  • 如果参数非法，SDK将会重置wxAppId为空字符串。
  • 如果传入的wxAppId为null，将清除设置的微信AppId。

[h2]setChannel

Method

public void setChannel(String channel)

设置应用安装来源。仅第一次设置有效，重复设置不生效。

说明：
  • 设置应用安装来源也可以通过在“AndroidManifest.xml”文件中添加meta-data参数，设置install_channel的值来实现。详情请参见接入步骤。
  • 如果已在“AndroidManifest.xml”文件中设置了安装来源的值，那么通过该接口设置的channel值将不生效。

Parameters

Name

Description

channel

非空，长度不超过128字符。支持英文字母、阿拉伯数字、下划线、中划线和空格，不能以空格开头和结尾。

[h2]setPushTokenCollectionEnabled

Method

public void setPushTokenCollectionEnabled(boolean enabled)

设置是否允许采集pushToken。

说明：
  • 是否允许采集pushToken也可以通过在“AndroidManifest.xml”文件中添加meta-data参数，设置analyticskit_pushtoken_collection_enabled的值来实现。详情请参见（可选）配置AndroidManifest.xml文件。
  • 通过该接口设置的值，优先级高于通过“AndroidManifest.xml”文件设置的值。

Parameters

Name

Description

enabled

是否允许采集pushToken。默认值为true，即允许采集。

  • true：允许
  • false：不允许
    说明：

    此接口设置的值为false时，setPushToken接口调用不生效。

[h2]setPropertyCollection

Method

public void setPropertyCollection (String property, boolean enabled)

设置是否允许采集系统属性，支持关闭和开启userAgent属性是否采集。

说明：
  • 禁止采集系统属性也可以通过在“AndroidManifest.xml”文件中添加meta-data参数，设置analyticskit_properties_collection_disabled的值来实现。详情请参见（可选）配置AndroidManifest.xml文件。
  • 通过该接口设置的值，优先级高于通过“AndroidManifest.xml”文件设置的值。

Parameters

Name

Description

property

系统属性，仅支持userAgent。

enabled

是否允许采集系统属性。默认值为true，即允许采集。

  • true：允许
  • false：不允许

[h2]setCustomReferrer

Method

public void setCustomReferrer(String customReferrer)

设置自定义Referrer。

说明：

该接口仅第一次调用生效。

Parameters

Name

Description

customReferrer

自定义Referrer。 非空，长度不超过256字符。

[h2]onNewIntent

Method

public void onNewIntent(Intent intent)

在Activity的onNewIntent中调用此接口，用于采集Push营销点击事件CAMPAIGNPUSHCLICK，提高点击率。

说明：

如果您的应用有使用智能运营服务，请在所有Push消息落地页Activity的onNewIntent方法中回调此接口，详情请参见调用onNewIntent方法。

Parameters

Name

Description

intent

页面启动的新Intent。

Sample code：

“Java”
// 在Activity的onNewIntent中调用
public class MainActivity extends Activity {
    private HiAnalyticsInstance instance;
    @Override
    protected void onCreate(Bundle savedInstanceState){
        instance = HiAnalytics.getInstance(this);
    }	
    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        if (instance != null) {
            instance.onNewIntent(intent);
        }
    }
}
“Kotlin”
// 在Activity的onNewIntent中调用
class MainActivity : AppCompatActivity() {
    private lateinit var instance: HiAnalyticsInstance
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        instance = HiAnalytics.getInstance(this);
    }
    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        instance.onNewIntent(intent)
    }
}

[h2]getDataUploadSiteInfo

Method

public String getDataUploadSiteInfo()

获取当前数据上报的数据处理位置。

Returns

Type

Description

String

数据处理位置国家码，全球四个数据处理位置中的一个（CN/SG/RU/DE）。