目录

接入Analytics

分析服务提供基于您上报事件的分析数据模型。

分析数据模型采用了Event-Param-User模型来记录数据,通过不同的参数对事件进行描述,同时对用户的特征也进行了描述。

术语

名称

说明

Event

事件

描述一个用户在某个时间点、某个地方、以某种方式完成了某个具体的事情。包含who、when、where、how、what等关键要素。

Param

参数

事件上报的关联参数。如加入购物车事件中的商品名称参数和商品价格参数,支持后续的深入分析。

UserProfiles

用户属性

用户的属性表,常见的用户属性有设备型号、应用版本、自定义的用户属性(如食品偏好)等。

Analytics Kit会收集AAID。AAID是应用匿名标识符,每个App在同一个设备上会分配不同的AAID。AAID用于连通华为提供的各项服务,例如Push、分析服务和远程配置等。

AAID会在如下场景重置:

接入步骤

  1. 配置应用安装来源。

    通过配置应用安装来源,您可以自主设置安装来源,例如:可以用于分析下载应用的应用市场,解析营销方案的实际效果。

    打开您的工程“AndroidManifest.xml”文件,配置应用的安装来源。在“application”模块根节点下添加meta-data参数,格式如下。

    <application>
        ……
        <meta-data
            android:name="install_channel"
            android:value="install_channel_value">
        </meta-data>
        ……
    </application>

    将“install_channel_value”替换为您的应用安装来源。例如:安装来源为华为应用市场,则将“install_channel_value”替换为“AppGallery”。

    • 安装来源命名规范:支持英文字母、阿拉伯数字、下划线、中划线和空格,不能以空格开头和结尾,长度不超过128个字符。可填写便于您记忆和理解的安装来源名称。
    • 应用安装来源也可以通过setChannel接口进行设置。通过接口设置的值,优先级低于通过“AndroidManifest.xml”文件配置的值,如果“AndroidManifest.xml”中配置的安装来源有值,则setChannel接口设置的值不生效。
  2. 初始化Analytics SDK。

    SDK通过getInstance接口根据配置完成初始化。

    • SDK初始化时会发送网络请求,请您务必在用户同意隐私协议后再初始化SDK。设置能否发送网络请求实现方法详情请参见为满足监管要求,集成SDK后要求用户在未同意访问网络前不能发送任何网络请求,如何处理?
    • 必须在第一个Activity或者Application的onCreate中初始化Analytics SDK,否则会导致生命周期相关事件采集不准确。
    • 此处入参context为Activity类型。自2.3.0.304版本开始,已支持Context类型初始化。
    • 初始化Analytics SDK时,如果是Context方式初始化,并且Context是从Application获取,将影响LAUNCHAPP事件部分参数的自动采集,某些场景取不到App的启动方式。
    “Java”
    HiAnalyticsInstance instance = HiAnalytics.getInstance(context);
    “Kotlin”
    val instance = HiAnalytics.getInstance(context)
  3. (可选)如果您需要从Google Play查询Referrer,可以添加如下示例代码。
    1. 在应用的“build.gradle”文件中添加如下依赖。
      implementation 'com.android.installreferrer:installreferrer:2.2'
    2. 在初始化分析服务SDK之后,调用setCustomReferrer方法设置自定义Referrer。
      “Java”
      // 获取HiAnalyticsInstance实例
      HiAnalyticsInstance instance = HiAnalytics.getInstance(context);
      final InstallReferrerClient client = InstallReferrerClient.newBuilder(getBaseContext()).build();
      client.startConnection(new InstallReferrerStateListener() {
          @Override
          public void onInstallReferrerSetupFinished(int responseCode) {
              if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
                  try {
                      ReferrerDetails details = client.getInstallReferrer();
                      // 设置自定义Referrer
                      instance.setCustomReferrer(details.getInstallReferrer());
                  } catch (RemoteException exception) {
                      // 捕获异常
                  }
              }
          }
          @Override
          public void onInstallReferrerServiceDisconnected() {
              // 断开service
          }
      });
      “Kotlin”
      // 获取HiAnalyticsInstance实例
      val instance = HiAnalytics.getInstance(this);
      val client: InstallReferrerClient = InstallReferrerClient.newBuilder(baseContext).build()
      client.startConnection(object : InstallReferrerStateListener {
          override fun onInstallReferrerSetupFinished(responseCode: Int) {
              if (responseCode == InstallReferrerClient.InstallReferrerResponse.OK) {
                  try {
                      val details: ReferrerDetails = client.getInstallReferrer()
                      // 设置自定义Referrer
                      instance.setCustomReferrer(details.getInstallReferrer())
                  } catch (exception: RemoteException) {
                      // 捕获异常
                  }
              }
          }
          override fun onInstallReferrerServiceDisconnected() {
              // 断开service
          }
      })
  4. (可选)设置上报策略。

    Analytics SDK提供了四种事件上报策略,支持多种策略自由组合,任何一种策略满足时即可触发事件上报。您可以根据场景选择合适的事件上报策略。

    如果设置上报策略,建议包含应用切后台上报策略,防止应用退出后部分事件缓存在本地不能及时上报。

    策略

    描述

    说明

    ON_APP_LAUNCH_POLICY

    应用启动上报策略

    应用启动时上报事件。选择该策略时会立即上报一次,此后每次应用启动时上报一次。

    ON_MOVE_BACKGROUND_POLICY

    应用切后台上报策略

    应用切后台时上报事件,包括应用退出。

    ON_SCHEDULED_TIME_POLICY

    定时上报策略

    根据指定的间隔时间上报事件,取值范围为【60-1800】秒(默认60秒),如果设置的值超过给定范围则取边界值。

    ON_CACHE_THRESHOLD_POLICY

    阈值上报策略

    缓存事件条数达到阈值时上报事件,取值范围为【30-1000】条(默认30条),如果设置的值超过给定范围则取边界值。

    • 以上上报策略仅在非调试模式下生效。上报策略持久化保存。
    • 应用切后台上报策略和阈值上报策略为必选策略,无论设置什么策略,这两个策略都会生效,但是可以改变阈值上报策略的阈值。
    • 多次调用设置上报策略的接口,会刷新上报策略,仅最后一次设置的策略生效,请谨慎多次调用。
    • 当策略满足触发事件上报时,如果没有网络,则会将事件缓存在本地,等待下次条件满足继续上报。
  5. 如果您的应用使用了智能运营服务,请务必调用onNewIntent接口。
  6. 通过onEvent接口记录定义事件。

    事件的定义请参见自动采集事件、通用、自定义事件。

  7. 请参见API参考,调用接口实现各类功能。例如:设置用户属性setUserProfile。

示例代码

  1. agconnect-services.json文件导入成功后,在第一个Activity的onCreate中初始化Analytics SDK,获得HiAnalyticsInstance实例。

    若agconnect-services.json文件不正确,则无法进行埋点。导入agconnect-services.json文件请参见集成SDK。

    “Java”
    @Override  
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        // 打开SDK日志开关  
        HiAnalyticsTools.enableLog();
        HiAnalyticsInstance instance = HiAnalytics.getInstance(this);
        // 或者使用Context初始化
        Context context = this.getApplicationContext();
        HiAnalyticsInstance instance = HiAnalytics.getInstance(context);
        // (可选)设置用户属性
        instance.setUserProfile("userKey","value"); 
    }
    “Kotlin”
    override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
         // 打开SDK日志开关
         HiAnalyticsTools.enableLog()
         val instance = HiAnalytics.getInstance(this)
         // 或者使用Context初始化
         val context = this.applicationContext
         val instance = HiAnalytics.getInstance(context)
         // (可选)设置用户属性
         instance.setUserProfile("userKey", "value")
    }
  2. (可选)设置应用切后台上报策略和定时上报策略。
    “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)
  3. (可选)如果您的应用使用了智能运营服务,请务必在Activity的onNewIntent中调用Analytics SDK的onNewIntent方法。
    “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)
        }
    }
  4. 在代码合适位置插入埋点代码。
    “Java”
    // 自定义埋点,在工程合适位置插入埋点代码 
    Bundle bundle = new Bundle(); 
    bundle.putString("exam_difficulty", "high"); 
    bundle.putString("exam_level", "1-1"); 
    bundle.putString("exam_time", "20190520-08"); 
    instance.onEvent("begin_examination", bundle); 
    // 预置事件埋点 
    Bundle bundle_pre = new Bundle(); 
    bundle_pre.putString(HAParamType.PRODUCTID, "item_ID"); 
    bundle_pre.putString(HAParamType.PRODUCTNAME, "name"); 
    bundle_pre.putString(HAParamType.CATEGORY, "category"); 
    bundle_pre.putLong(HAParamType.QUANTITY, 100L); 
    bundle_pre.putDouble(HAParamType.PRICE, 10.01); 
    bundle_pre.putDouble(HAParamType.REVENUE, 10); 
    bundle_pre.putString(HAParamType.CURRNAME, "currency"); 
    bundle_pre.putString(HAParamType.PLACEID, "location_ID"); 
    instance.onEvent(HAEventType.ADDPRODUCT2WISHLIST, bundle_pre);
    “Kotlin”
    // 自定义打点,在工程合适位置插入打点代码
    val bundle = Bundle()
    bundle.putString("exam_difficulty", "high")
    bundle.putString("exam_level", "1-1")
    bundle.putString("exam_time", "20190520-08")
    instance.onEvent("begin_examination", bundle)
    // 预置事件打点
    val bundle_pre = Bundle()
    bundle_pre.putString(HAParamType.PRODUCTID, "item_ID")
    bundle_pre.putString(HAParamType.PRODUCTNAME, "name")
    bundle_pre.putString(HAParamType.CATEGORY, "category")
    bundle_pre.putLong(HAParamType.QUANTITY, 100L)
    bundle_pre.putDouble(HAParamType.PRICE, 10.01)
    bundle_pre.putDouble(HAParamType.REVENUE, 10.0)
    bundle_pre.putString(HAParamType.CURRNAME, "currency")
    bundle_pre.putString(HAParamType.PLACEID, "location_ID")
    instance.onEvent(HAEventType.ADDPRODUCT2WISHLIST, bundle_pre)

接入调试

在开发过程中可以启用调试模式,实时查看事件的记录情况,观察具体结果并根据需要进行调整。

[h2]开启/停用调试模式

(可选)配置“AndroidManifest.xml”文件

  1. 配置是否允许采集广告标识符。

    是否允许采集广告标识符,您可以通过配置广告标识符采集开关的值来实现。配置方法如下:

    打开您的工程“AndroidManifest.xml”文件,在“application”模块根节点下添加meta-data参数,格式如下。

    <application>
        ……
        <meta-data
            android:name="analyticskit_adsid_collection_enabled"
            android:value="true">
        </meta-data>
        ……
    </application>

    是否允许采集广告标识符默认的value值为true,即允许采集。您可以根据需要进行设置。

    是否允许采集广告标识符也可以通过setCollectAdsIdEnabled接口进行设置。通过接口设置的值,优先级高于通过“AndroidManifest.xml”文件设置的值。

  2. 配置是否允许采集pushToken。

    是否允许采集pushToken,您可以通过配置pushToken采集开关的值来实现。配置方法如下:

    打开您的工程“AndroidManifest.xml”文件,在“application”模块根节点下添加meta-data参数,格式如下。

    <application>
        ……
        <meta-data
            android:name="analyticskit_pushtoken_collection_enabled"
            android:value="true">
        </meta-data>
        ……
    </application>

    是否允许采集pushToken默认的value值为true,即允许采集。您可以根据需要进行设置。

    是否允许采集pushToken也可以通过setPushTokenCollectionEnabled接口进行设置。通过接口设置的值,优先级高于通过“AndroidManifest.xml”文件设置的值。

  3. 配置禁止采集系统属性。

    禁止采集系统属性,您可以通过如下配置方法来实现:

    打开您的工程“AndroidManifest.xml”文件,在“application”模块根节点下添加meta-data参数,格式如下。

    <application>
        ……
        <meta-data
            android:name="analyticskit_properties_collection_disabled" 
            android:value="userAgent">
        </meta-data>
        ……
    </application>

    value的值为禁止采集的属性字符串,仅支持userAgent。

    是否允许采集系统属性也可以通过setPropertyCollection接口进行设置。通过接口设置的值,优先级高于通过“AndroidManifest.xml”文件设置的值。