分析服务(HMS Core)快速入门
华为分析服务(HUAWEI Analytics Kit)是针对移动应用、Web、快应用、快游戏、小程序等产品的一站式用户行为分析平台,贴合业务场景,提供数据采集、数据管理、数据分析、数据应用的一体化解决方案,驱动企业实现精准拉新、产品优化、精益运营、业务增长。
提供给跨部门、跨角色人员的一站式数智化分析平台
- 基于SDK自动采集的用户事件、用户属性及开发者上报的用户行为数据,华为分析服务可自动生成数据看板、留存分析报告、用户分析报告、行为分析报告、用户生命周期报告、版本分析报告、崩溃分析报告等,支持多维度下钻与对比分析能力,支撑市场拓展人员、产品经理、活动运营、用户运营、技术开发等不同人员的日常数据分析需求,驱动业务智能分析与决策。
应用场景
预定义事件 + 自定义事件,灵活支撑用户行为分析。
基于对用户行为的洞察,使用受众群体构建能力,对受众群体开展相应的营销活动。
通过概览和通用的分析能力,有效衡量营销活动是否达到预期效果;并帮助开发者轻松获取常用指标和常见问题的答案。
版本更新说明
当前版本:[3.x] 2.4.0_6.12.0.301
- SDK 升级到 6.12.0.301
版本:[3.x] 2.3.5_6.12.0.300
完善内部实现
SDK 升级到 6.12.0.300
[3.x] 2.2.1_6.10.0.303
- 升级SDK版本。
0.5.7_5.0.5.301
- 新增部分预制事件及参数。
v0.5.5_5.0.5.301
更新分析服务 SDK 到版本 5.0.5.301。
新增对设置应用安装来源的支持。
新增
setReportPolicies
接口来设置上报策略。新增部分游戏行业和电商行业的预置事件及参数。
setUserProfile
方法中传入null
或者undefined
,可以删除对应的用户属性。
v0.5.3_5.0.1
- 集成华为 HMS 分析服务。
一键接入分析服务
开通服务
使用 Cocos Creator 打开需要接入分析服务的项目工程。
点击菜单栏的 面板 -> 服务,打开 服务 面板,在 HUAWEI HMS Core 内选择 分析服务,进入服务详情页。然后点击右上方的 启用 按钮即可开通服务。
参考 配置 AppGallery Connect 文档,完成开发者注册、创建应用、开通华为分析服务参数配置和开启 API 步骤。
在分析服务面板的 参数配置 中填写 应用安装来源。例如:应用的安装来源是华为应用市场,就可以填写 AppGallery。安装来源命名规范:支持英文字母、阿拉伯数字、下划线、中划线和空格,长度不超过 128 个字符。当命名仅包含数字时不能以空格为开头/结尾,
配置华为参数文件
大部分的华为相关项目都需要用到 agconnect-services.json
配置文件。若有新开通服务等操作,请及时更新该文件。
登录 AppGallery Connect 后台,在 项目列表 -> 应用列表 中找到对应的应用。
在 项目设置 页面的 应用 区域,点击
agconnect-services.json
下载配置文件。agconnect-services.json
文件在下载或者更新完成后,必须手动拷贝 到工程目录的settings
目录下。Cocos Creator v2.4.3 及以上版本,若发布到 HUAWEI AppGallery Connect,开发者可直接在 构建发布 面板中选取下载或更新后的配置文件,不需要手动拷贝。
验证服务是否接入成功
完成分析服务接入步骤后,无需改动代码,即可 发布到 Android 平台。请确保 构建发布 面板中的包名与华为后台设置的包名一致。
工程运行到手机后,登录 AppGallery Connect 后台,打开对应项目,进入 华为分析 -> 用户分析 -> 新增用户,若能看到新开通的服务有新增用户信息(通常会在 10 分钟内显示),即为接入成功。
Sample 工程
开发者可以通过 Sample 工程快速体验分析服务。
点击分析服务面板中的 Sample 工程 按钮,Clone 或下载 HUAWEI Sample 工程,并在 Cocos Creator 中打开。
参照上文开通分析服务并配置华为参数文件后,可通过 Creator 编辑器菜单栏的 项目 -> 构建发布 打开 构建发布 面板来构建编译工程。Creator v2.4.1 及以上版本,可 发布到 HUAWEI AppGallery Connect,Creator v2.4.1 以下的版本可 发布到 Android 平台。
需要在已安装 HMS Core 服务的华为手机上测试。
Sample 工程运行到手机后,点击首页的 Analytics 按钮,即可进入功能界面进行测试。
开发指南
分析服务预设了一些 自动采集事件,无需开发者埋点或主动调用,即可实现此类事件的自动采集。
分析服务插件启动时,已调用 SDK 的初始化,开发者无需再做调用。。
自定义事件(埋点)
onEvent(eventId: any, params: any): void
记录自定义事件(埋点)是分析服务的主要调用方法。针对自动采集事件、预置事件无法满足的个性化分析需求,开发者可上报自定义事件。
开发者可能有个性化的事件需要打点分析,分析服务也支持开发者自定义事件并扩展事件参数,或是对预定义事件新增个性化参数。
比如对教育类的应用,可以添加自定义事件 begin_examination
来表示 进入新考试 的事件,并给该事件增加参数 exam_difficulty
来定义 考试难度,以此满足特定业务场景的分析。
参数说明:
参数 | 说明 |
---|---|
eventId | 事件标识符。自定义非空,由数字、字母、下划线组成,不能以数字开头,不能包含空格,长度不超过 256 字符,不能使用自动采集事件ID,建议优先使用预制事件ID。 |
params | 事件携带的信息。传入参数键值对个数不超过 2048,同时大小不超过 200KB。传入参数 key 值由数字、字母、下划线组成,不能以数字开头。 |
示例:
let eventName = 'myEvent';
let params = {
name: 'userName',
age: 18,
others: {
stature: 199,
level: 100
}
};
huawei.hms.analytics.analyticsService.onEvent(eventName, params);
可选方法
是否打开打点采集能力
setAnalyticsEnabled(enable: boolean): void
关闭后将不再记录任何数据。
参数说明:
参数 | 说明 |
---|---|
enabled | 是否打开采集开关,默认打开。 true:打开 false:关闭 |
示例:
huawei.hms.analytics.analyticsService.setAnalyticsEnabled(true);
设置用户 ID
setUserId(userId: string): void
调用该接口时,如果旧 userId 不为空字符串且和新 userId 不同,会重新生成新的 Session 会话。若开发者不希望使用 setUserId
标识用户(如用户退出时),必须将 userId 设为 null
。
用于应用标识用户的 ID,在分析的服务侧通过此标识进行关联用户数据。使用 userId 需要遵守相关隐私规范,请在开发者应用的隐私声明中进行声明。
参数说明:
参数 | 说明 |
---|---|
userId | 用户 ID,非空,长度不超过 256 字符。 |
示例:
huawei.hms.analytics.analyticsService.setUserId("a123456");
设置用户属性
setUserProfile(name: string, value: string): void
用户属性值将在整个应用程序的生命周期和会话期间保持不变。最多支持 25 个用户属性名称,如果后面设置属性有重复的 name,则刷新。
分析服务自动采集了一些 用户属性,开发者无需埋点即可使用。
参数说明:
参数 | 说明 |
---|---|
name | 用户属性的标识符。非空,长度不超过 256 字符,不支持空格和不可见字符。 |
value | 属性值。长度不超过 256 字符,传递 null 或者 undefined 可删除对应用户属性 |
示例:
let name = 'profile1';
let value = 'value1';
huawei.hms.analytics.analyticsService.setUserProfile(name, value);
console.log('setUserProfile...', name, value);
设置 Push Token
setPushToken(token: string): void
在通过 HMS Core 推送服务获取到 Push Token 后,开发者可以使用该方法保存 Push Token,以便定义用户,并创建 HCM 通知任务。
若接入推送功能,调用 getToken
方法返回的回调即为所需的 Push Token。
参数说明:
参数 | 说明 |
---|---|
token | Push Token,非空,长度不超过 256 字符。 |
示例:
huawei.hms.analytics.analyticsService.setPushToken("XXX");
设置重新开始新 Session 的最短时间间隔
setMinActivitySessions(time: number): void
此方法设置的时间间隔,用于指定 App 在后台运行一段时间后,再次切回前台时生成新会话的时间。默认 30 秒。
参数说明:
参数 | 说明 |
---|---|
milliseconds | 最短 Session 刷新间隔。单位:毫秒。 |
示例:
let value = 1000 * 60 * 60;
huawei.hms.analytics.analyticsService.setMinActivitySessions(value);
设置 Session 超时时长
setSessionDuration(time: number): void
设置 Session 超时时长。App 一直在前台运行,当两个相邻事件的时间间隔超过此方法设置的阈值时,将生成一个新的会话。默认 30 分钟。
参数说明:
参数 | 说明 |
---|---|
milliseconds | 最短 Session 刷新间隔。单位:毫秒。 |
示例:
let value = 1000 * 60 * 60;
huawei.hms.analytics.analyticsService.setSessionDuration(value);
清除本地缓存的所有采集数据
clearCachedData(): void
清除本地缓存的所有采集数据,包括发送失败的缓存数据。
示例:
huawei.hms.analytics.analyticsService.clearCachedData();
获取 App Instance ID
getAAID(): void
从 AGC 服务中获取 App Instance ID,需使用 huawei.hms.analytics.analyticsService.once
获取单次回调,或者使用 huawei.hms.analytics.analyticsService.on
监听回调。
示例:
huawei.hms.analytics.analyticsService.once(huawei.hms.HMS_ANALYTICS_EVENT_LISTENER_NAME.GET_AAID, (result) => {
console.log('getAAID...', JSON.stringify(result));
});
huawei.hms.analytics.analyticsService.getAAID();
获取预定义或者自定义的用户属性
getUserProfiles(preDefined: boolean): void
支持 A/B test 特性,获取预定义或者自定义的用户属性,需使用 huawei.hms.analytics.analyticsService.once
获取单次回调,或者使用 huawei.hms.analytics.analyticsService.on
监听回调。
参数说明:
参数 | 说明 |
---|---|
preDefined | 是否获取预定义用户属性,默认打开。 true:获取预定义用户属性 false:获取开发者自定义用户属性 |
示例:
huawei.hms.analytics.analyticsService.once(huawei.hms.HMS_ANALYTICS_EVENT_LISTENER_NAME.GET_USER_PROFILES, (result) => {
console.log('getUserProfiles...', JSON.stringify(result));
});
huawei.hms.analytics.analyticsService.getUserProfiles();
自定义进入页面事件
pageStart(pageName: string, pageClassOverride: string): void
自定义页面开始事件,只在非 Activity 的页面调用,Activity 页面会自动采集,无需调用。如果在 Activity 页面调用,会导致页面进出事件统计不准确。
调用本方法后,需要调用 pageEnd
方法配对使用。
参数说明:
参数 | 说明 |
---|---|
pageName | 当前页面名称,长度不超过 256 字符,不可为空。 |
pageClassOverride | 当前页面类名,长度不超过 256 字符,不可为空。 |
示例:
huawei.hms.analytics.analyticsService.pageStart("pageName1", "pageClassOverride1");
自定义退出页面事件
pageEnd(pageName: string): void
参数说明:
参数 | 说明 |
---|---|
pageName | 当前结束的页面名称,长度不超过 256 字符,不可为空,需要和对应 pageStart 内传入的 pageName 相同。 |
示例:
huawei.hms.analytics.analyticsService.pageEnd("pageName1");
设置自动上报策略
setReportPolicies(...reportPolicies: ReportPolicy[])
参数说明:
参数 | 说明 |
---|---|
policies | 支持四种上报策略,可以同时设置多个策略。 ON_APP_LAUNCH_POLICY:应用启动上报策略,当应用启动时会立即上报一次,此后每次应用启动时都会上报一次。 ON_MOVE_BACKGROUND_POLICY:应用切后台(包括应用退出)上报策略。 ON_SCHEDULED_TIME_POLICY:定时上报策略,根据指定的间隔时间轮循上报事件,取值范围为 60-1800 秒,如果设置的值超过给定范围则取边界值。 ON_CACHE_THRESHOLD_POLICY:阈值上报策略,缓存事件条数达到阈值时上报事件,取值范围为 30-1000 条(默认 30 条),如果设置的值超过给定范围则取边界值。 |
说明:
以上上报策略仅在 非调试模式 下生效。
应用切后台上报策略和阈值上报策略为默认策略,当没有设置上报策略时,这两种策略自动生效。如果设置了上报策略但是不包含应用切后台上报策略,此时应用切后台上报策略不会生效。
阈值上报策略为必选策略,无论设置什么策略,该策略都会生效,但是可以改变它的阈值。
多次调用设置上报策略的接口,会刷新上报策略,仅最后一次设置的策略生效,请谨慎多次调用。
当策略满足触发事件上报时,如果没有网络,则会将事件缓存在本地,等待下次条件满足继续上报。
上报策略持久化保存。
如果仅设置启动上报或者定时上报,然后卸载应用,可能会造成部分打点数据丢失。
示例:
let ReportPolicy = huawei.hms.analytics.ReportPolicy;
let moveBackgroundPolicy = ReportPolicy.ON_MOVE_BACKGROUND_POLICY;
let scheduledTimePolicy = ReportPolicy.ON_SCHEDULED_TIME_POLICY;
scheduledTimePolicy.threshold = 600;
huawei.hms.analytics.analyticsService.setReportPolicies(moveBackgroundPolicy, scheduledTimePolicy);
打开调试日志
static enableLog(level?: LOG_LEVEL): void
打开调试日志。若传入 level 参数,则可自定义输出的最小日志级别。
该方法在 AnalyticsTools
类中,请注意调用写法。
参数说明:
参数 | 说明 |
---|---|
level | 可选,指定调试日志的级别。 日志级别: huawei.hms.LOG_LEVEL.debug, huawei.hms.LOG_LEVEL.info, huawei.hms.LOG_LEVEL.warn, huawei.hms.LOG_LEVEL.error。 |
示例:
huawei.hms.analytics.AnalyticsTools.enableLog();
huawei.hms.analytics.AnalyticsTools.enableLog(huawei.hms.LOG_LEVEL.debug);
设置是否限制数据分析能力
setRestrictionEnabled(isEnabled:boolean):void
限制分析开关默认值为NO,即默认不限制数据分析能力。
参数说明:
参数 | 说明 |
---|---|
isEnabled | 打开或关闭数据分析能力。默认值为NO,即打开数据分析能力。 |
YES:关闭
NO:打开|
示例
huawei.hms.analytics.analyticsService.setRestrictionEnabled(true);
设置是否允许采集广告标识符
setCollectAdsIdEnabled(isEnabled:boolean):void
参数说明:
参数 | 说明 |
---|---|
isEnabled | 打开或关闭广告标识符的采集。 |
YES:打开 NO:关闭|
示例
huawei.hms.analytics.analyticsService.setCollectAdsIdEnabled(true);
设置是否限制数据共享
setRestrictionShared(shared:boolean):void
说明
限制数据共享开关默认值为false,即默认开启数据共享能力
仅中国大陆可用,非中国大陆调用无效。
参数说明
参数 | 说明 |
---|---|
shared | 打开或关闭数据共享能力。默认值为false,即打开数据共享能力。 |
true:关闭 false:打开|
示例
huawei.hms.analytics.analyticsService.setRestrictionShared(true);
获取当前限制数据共享开关状态
setRestrictionShared (shared: boolean): void
说明
- 仅中国大陆可用,非中国大陆调用无效
示例
huawei.hms.analytics.analyticsService.once(huawei.hms.analytics.HMS_ANALYTICS_EVENT_LISTENER_NAME.IS_RESTRICTION_SHARED, (result) => {
console.log(
'isRestrictionShared',
JSON.stringify(result)
);
})
huawei.hms.analytics.analyticsService.isRestrictionShared();
添加默认事件参数
addDefaultEventParams (params: any | null | undefined): void
说明
添加默认事件参数,默认事件参数将被添加到除自动采集事件之外的所有事件中,默认事件参数与事件参数同名时,使用事件参数
参数最多支持100个键值对,每个键值对中key的长度不能超过256个字符,且只能由数字、字母、下划线组成,不能以数字开头;value长度不能超过256个字符,value只支持String、int、long、double、boolean、float、char、byte、short。
如果传入的params为null,将清除所有缓存的默认事件参数;如果传入的键值对中value为null,将删除对应的默认事件参数;如果传入的键值对中key已存在,将更新对应的默认事件参数
默认事件参数的个数和大小会被onEvent计入,请注意参数的使用限制
参数说明
参数 | 说明 |
---|---|
params | 键值对 object 或 null 或 undefined |
示例
let params = {
platform: 'windows',
os: 'win10',
};
huawei.hms.analytics.analyticsService.addDefaultEventParams(params);
设置微信openId
setWXOpenId (wxOpenId: string): void
参数说明
参数 | 说明 |
---|---|
wxOpenId | 非空,长度不超过256字符。如果参数非法,SDK将会重置wxOpenId为空字符串。如果传入的wxOpenId为null,将清除设置的微信openId。 |
示例
huawei.hms.analytics.analyticsService.setWXOpenId("testWXOpenId1");
设置微信unionId
setWXUnionId (wxUnionId: string): void
说明
- 若您不希望使用setWXUnionId标识用户(如用户退出时),必须将wxUnionId设为null。
参数说明
参数 | 说明 |
---|---|
wxUnionId | 非空,长度不超过256字符。如果参数非法,SDK将会重置wxUnionId为空字符串。如果传入的wxUnionId为null,将清除设置的微信unionId。 |
示例
huawei.hms.analytics.analyticsService.setWXUnionId("testWXUnionId1");
设置微信AppId
setWXAppId (wxAppId: string): void
参数说明
参数 | 说明 |
---|---|
wxAppId | 非空,长度不超过256字符。如果参数非法,SDK将会重置wxAppId为空字符串。如果传入的wxAppId为null,将清除设置的微信AppId。 |
示例
huawei.hms.analytics.analyticsService.setWXAppId("testWXAppId1");
设置应用安装来源
setChannel (channel: string): void
说明
仅第一次设置有效,重复设置不生效。
设置应用安装来源也可以通过在“AndroidManifest.xml”文件中添加meta-data参数,设置install_channel的值来实现。
如果已在“AndroidManifest.xml”文件中设置了安装来源的值,那么通过该接口设置的channel值将不生效。
参数说明
参数 | 说明 |
---|---|
channel | 非空,长度不超过128字符。支持英文字母、阿拉伯数字、下划线、中划线和空格,不能以空格开头和结尾。 |
示例
huawei.hms.analytics.analyticsService.setChannel("AppGallery");
设置是否允许采集pushToken
setPushTokenCollectionEnabled (enabled: boolean): void
说明
是否允许采集pushToken也可以通过在“AndroidManifest.xml”文件中添加meta-data参数,设置analyticskit_pushtoken_collection_enabled的值来实现
通过该接口设置的值,优先级高于通过“AndroidManifest.xml”文件设置的值。
参数说明
参数 | 说明 |
---|---|
enabled | 是否允许采集pushToken。默认值为true,即允许采集。true:允许 false:不允许。此接口设置的值为false时,setPushToken接口调用不生效。 |
示例
huawei.hms.analytics.analyticsService.setPushTokenCollectionEnabled(true);
设置是否允许采集系统属性
setPropertyCollection (property: string, enabled: boolean): void
说明
支持关闭和开启userAgent属性是否采集
禁止采集系统属性也可以通过在“AndroidManifest.xml”文件中添加meta-data参数,设置analyticskit_properties_collection_disabled的值来实现
通过该接口设置的值,优先级高于通过“AndroidManifest.xml”文件设置的值
参数说明
参数 | 说明 |
---|---|
property | 系统属性,仅支持userAgent |
enabled | 是否允许采集系统属性。默认值为true,即允许采集。true:允许 false:不允许 |
示例
huawei.hms.analytics.analyticsService.setPropertyCollection("userAgent", true)
设置自定义Referrer
setCustomReferrer (customReferrer: string): void
说明
- 该接口仅第一次调用生效。
参数说明
参数 | 说明 |
---|---|
customReferrer | 自定义Referrer。 非空,长度不超过256字符 |
示例
huawei.hms.analytics.analyticsService.setCustomReferrer("customReferrer1");
获取当前数据上报的数据处理位置
getDataUploadSiteInfo (): void
说明
- 获取数据处理位置国家码,全球四个数据处理位置中的一个
示例
huawei.hms.analytics.analyticsService.once(huawei.hms.analytics.HMS_ANALYTICS_EVENT_LISTENER_NAME.GET_DATA_UPLOAD_SITE_INFO, (result) => {
console.log('getDataUploadSiteInfo', JSON.stringify(result));
});
huawei.hms.analytics.analyticsService.getDataUploadSiteInfo();
个人数据处理说明
如何实现对最终用户数据的处理,请参考 个人数据处理说明。
其他
详细的功能说明,请参考服务指南。