秒针分析SDK部署指南(Flutter测试版本） #

A mzanalytics_mybmw flutter plugin project.

一、准备工作 🍭 #

1. 版本限制 #

Flutter SDK：>=1.17.0 。
Xcode 版本: >=12.0。
*MZAnalyticsIOS*SDK**适用于 iOS 9-iOS 14.0，请将iOS Deployment Target设置为iOS 9.0，。
*MZAnalyticsAndroid*SDK适用于Android 2.3.3（API Level 10）**及以上的设备。

建议： #

建议将sdk初始化方法放在获取设备id、存储等权限后执行，若将sdk 初始化方法放在授权之前，可能会影响激活归因等数据的准确性。

2. Flutter项目添加依赖 #

将mzanalytics_mybmw 添加至pubspec.yaml引用。

dependencies:  
mzanalytics_mybmw: ^${latestVersion}

在flutter项目中运行 flutter pub get

3. 集成准备 #

3.1 为应用申请AppId

在 https://tongji.cn.miaozhen.com网站中创建一款应用，您将获得一串随机的“dc-”开头的站点id，用于唯一标识您的一款应用。

3.2 AppId说明

appId为应用追踪的唯一标识，在 https://tongji.cn.miaozhen.com 网站中的站点-->站点信息内获取。

3.3 客户需在Android 平台上获取OAID时的配置

说明: 仅支持MSA SDK 1.0.25版本的OAID获取。
可依据客户个人需求决定是否配置。若配置，秒针分析SDK可采集OAID；若不配置，则无法获取OAID。请依据移动安全联盟官网推荐的MSA SDK集成方式引入。
移动安全联盟官网链接：https://msa-alliance.cn/col.jsp?id=120

3.4 Android SDK 权限配置 #

以下权限根据客户实际需求进行配置:

权限	权限描述	是否可选	不授权的影响
INTERNET	允许程序联网	必选项	SDK无法发送数据
READ_PHONE_STATE	允许访问手机设备的唯一标识信息	可选项	SDK无法获取设备ID
ACCESS_WIFI_STATE	允许读取WiFi状态变化	可选项	影响数据SDK数据发送频率
READ_EXTERNAL_STORAGE	允许读取SD卡上存储的数据	必选项	影响SDK读取标识唯一用户的CID和发送失败的历史数据
WRITE_EXTERNAL_STORAGE	允许写入标识唯一用户的CID等信息到SD卡	必选项	影响SDK存储标识唯一用户的CID和发送失败的数据写入

示例代码:

<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 网络状态相关权限 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 手机信息相关权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- SD卡读写权限 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

4. 运行环境配置 #

4.1 iOS运行环境配置

a. cd到iOS项目目录。   
b. 终端执行  `pod install`。   
c. 打开`Runner.xcworkspace` ,在`Pods->Development->mzanalytics_mybmw->..->Classes中找到sdkconfig.xml`, 拖到工程项目Runner中。

4.2 Android运行环境配置

a. 进入到android项目目录`app/src/main中`。       
b. 拷贝assets文件夹(包含sdkconfig.xml和supplierconfig.json)到`main`目录下。      
c. 在application标签中添加属性（appkey为纯数字）： 
     <meta-data
       android:name="com.miaozhen.mzsdk.appKey"
       android:value="xxxx" />
     <meta-data
       android:name="com.miaozhen.mzsdk.channelId"
       android:value="xxxxx" />

二、秒针分析SDK使用 #

flutter代码中引入头文件:

import 'package:mzanalytics_mybmw/mzanalytics_mybmw.dart';

1 调用示例 #

1.1 初始化SDK (必选埋点)

说明：使用时将xxxx替换为实际的AppId (iOS在api中传入，Android需在application标签中配置)

接口定义：

 Future<void> appid(String appid)

参数说明:

参数	类型	说明	是否必填
appid	String	为创建站点时的站点id	必填

示例代码 ：   
//在 https://tongji.cn.miaozhen.com 网站中创建一款应用，站点id为dc-2814；将2814传入该接口

MzanalyticsMybmw.appid("2814");

1.2 页面浏览 (可选埋点，与页面自动监听方案可二选一)

说明：
a. 用于监测页面浏览行为，在需要监测的页面启动方法中添加如下代码后，即可采集用户的页面浏览行为；
b. 如需在页面浏览数据上报时，需携带更多的信息，可使用自定义维度和自定义指标。【具体使用规则见文档中 1.9自定义维度和自定义指标使用方法 】

接口定义：

Future<void> trackPageView(Map parameter)

参数说明：

参数	类型	说明	是否必填
dt	String	需监测的页面名称	必填
customDimMetrics	Map	自定义维度和自定义指标集合名称	可选，业务场景中无需携带自定义维度和自定义指标时，customDimMetrics不写即可

customDimMetrics中需传递的自定义参数说明：

参数	类型	说明	是否必填
cd[1~25]	String	自定义维度,最多25个	选填
cm[1~25]	String类型的数值	自定义指标,最多25个	选填

不传递自定义维度和自定义指标的示例代码：
MzanalyticsMybmw.trackPageView({"dt": "首页"});//页面名称，如首页


传递自定义维度和自定义指标的示例代码：
 MzanalyticsMybmw.trackPageView({
                   "dt": "首页", 
                 "CustomDimMetrics": {
                   "cd1":"ID88888",//需统计的自定义维度1的名称，如浏览该页面的用户Id              
                   "cd2": "小明机器人", //需统计的自定义维度2的名称，如浏览页面的用户名称
                   "cm1": "1" //需统计的自定义指标的数值，如用户个数为1
                 }  
});

1.3 自定义事件 (可选埋点)

说明：
a. 用户与App的交互动作，可添加自定义事件代码进行统计，在需要自定义埋点的按钮或其他控件的点击方法中，添加如下代码；
b. 如需在自定义事件数据上报时，需携带更多的信息，可使用自定义维度和自定义指标。【具体使用规则见文档中 1.9自定义维度和自定义指标使用方法 】

接口定义：

Future<void>  trackEvent(Map parameter)

参数说明：

参数	类型	说明	是否必填
ec	String	事件分类	必填
ea	String	事件动作	选填
el	String	事件标签	选填
ev	String类型的数值	事件价值	选填
customDimMetrics	Map	自定义维度和自定义指标集合名称	可选，没有自定义维度和自定义指标时，customDimMetrics不写即可

customDimMetrics中需传递的自定义参数说明：

参数	类型	说明	是否必填
cd[1~25]	String	自定义维度,最多25个	选填
cm[1~25]	String类型的数值	自定义指标,最多25个	选填

 不传递自定义维度和自定义指标的示例代码：
MzanalyticsMybmw.trackEvent({
               "ec": "领取奖励",//需统计的事件分类名称，如领取奖励
               "ea": "Click",//需统计的事件动作名称，如Click
               "el": "任务箱领取奖励", //需统计的事件标签，如任务箱领取奖惩
               "ev": "10" //需统计的事件价值,如10
             });
             
传递自定义维度和自定义指标的示例代码：
MzanalyticsMybmw.trackEvent({
                   "ec": "领取奖励",
                   "ea": "Click",
                   "el": "任务箱领取奖励",
                   "ev": "10",
                 "CustomDimMetrics": { 
                   "cd3": "首次登陆任务箱",  //需统计的自定义维度名称，如任务箱名称
                   "cm2": "2"  //需统计的自定义指标数值，如打开的任务箱个数，共2个
                 }
                 });

1.4 高级事件 (可选埋点)

说明：
a. 高级事件统计代码可统计更多维度、指标的用户交互事件。用户可根据统计业务需要，设定所要统计的维度、指标。

b. 如需在高级事件数据上报时，需携带更多的信息，可使用自定义维度和自定义指标。【具体使用规则见文档中 1.9自定义维度和自定义指标使用方法 】

接口定义：

Future<void>  trackSiteCustomEvent(Map parameter)

参数说明：

参数	类型	说明	是否必填
customEvent	Map	包含高级事件id、以及高级事件维度、指标数均以实际在系统中创建的⾼级事件为准	必填
customDimMetrics	Map	自定义维度和自定义指标集合名称	可选，没有自定义维度和自定义指标时，customDimMetrics可不传

CustomEvent中需传递的高级事件参数说明：

参数	类型	说明	是否必填
caid	Int	高级事件id	必填
cal[1~20]	String	高级事件维度,最多20个	选填
cav[1~20]	Int	高级事件指标,最多20个	选填

customDimMetrics中需传递的自定义参数说明：

参数	类型	说明	是否必填
cd[1~25]	String	自定义维度,最多25个	选填
cm[1~25]	Int	自定义指标,最多25个	选填

 不传递自定义维度和指标的示例代码：
 MzanalyticsMybmw.trackSiteCustomEvent({
                 "CustomEvent": {
                   "caid": "1", //需统计的高级事件Id，需要在秒针分析系统中配置高级事件后得到，如本处意为高级事件Id为1的注册事件
                   "cal1": "2020/01/10",  //需统计的高级事件维度1，如注册的时间
                   "cal2": "北京",//需统计的高级事件维度2，如注册的地点
                   "cav1": "20"  //需统计的高级事件指标,如 触发注册事件的用户年龄
                 }
               });


传递自定义维度和指标的示例代码：
 MzanalyticsMybmw.trackSiteCustomEvent({
                 "CustomEvent": {
                   "caid": "1",
                   "cal1": "2020/01/10",
                   "cal2": "北京",
                   "cav1": "20"
                 },
                 "CustomDimMetrics": {
                   "cd1": "ID88888",//需统计的自定义维度，如触发注册事件的用户Id
                   "cm1": "1"//需统计的自定义指标，如触发高级事件的用户数1
                 }
               });

1.5 心跳事件 (可选埋点)

说明：可在用户退出App或页面时埋点该事件，用于统计更准确的App使用时长。

接口定义：

 Future<void> trackPulse()

参数说明：无

示例代码：

 MzanalyticsMybmw.trackPulse();

1.6 获取访客id（可选调用api，不用于sdk统计数据）

说明：访客id是秒针分析标识唯一用户的id，该接口可用于客户获取秒针分析SDK生成的cid。

接口定义：

  Future<String> getCid()

参数说明：无

示例代码：

 MzanalyticsMybmw.getCid();

1.7 DeepLink(可选埋点)

说明：用于统计已添加秒针分析广告参数后的deeplink链接的监听，若不添加秒针广告参数，普通的deeplink链接吊起app的行为不会被统计。

 接口定义：
 static Future<void> onDeepLinkReceived(String url)

参数说明：

参数	类型	说明
url	String	deeplink跳转后收到的url（必填）

 示例代码：      
//deeplink      
  MzanalyticsMybmw.onDeepLinkReceived(url);

url示例：

mltsite://event/page/view/last?name=ceshi&age=30&mz_ca=2220134&mz_sp=35790

格式规范：
scheme://host/path?key1=value1&key2=value2&mz_ca=2220134&mz_sp=35790 说明：
a. 问号?前面客户可以自己定义；
b. 问号后面key和value连接必须用=，不同key-value拼接必须用&；
c. 同时存在mz_ca和mz_sp归为deeplink流量，否则归为普通流量；
d. mz_ca合法是7位，mz_sp合法是5位。

1.8 SDKConfig权限配置(根据业务需求自行配置)

项目中 sdkconfig.xml是开关配置文件。为 idfa、imei、oaid(可选项，如需获取按移动安全联盟推荐的方式集成MSA SDK即可)、adid、autotrackpage配置开关。

a. 当设置idfa、imei、oaid、adid配置中的isRequired的value为true时，获取以上id；
b. 当设置idfa、imei、oaid、adid配置中的isRequired的value为false时，不获取以上id；
c. 当需要页面自动监听时，请将autotrackpage的值设置为false，需要页面自动监听时，将值设置为true；
d. 当需要页面自动监听，但需过滤特定页面A的自动监听时，修改manualtrackpage对应的value为其页面标题，设定后，A页面不会被自动监听。若有多个页面无需自动监听，则在value部分输入多个页面标题即可，多个页面标题之间用“、”分隔。

注意:在填写无需自定动监听的页面标题时，页面标题中不可含有中文输入法下的“、”，否则会引起过滤不正确的情况。

1.9 自定义维度和指标的使用方法

在页面浏览、自定义事件、高级事件数据上报时，需额外携带其他信息时，则可以使用秒针分析提供的自定义维度和自定义指标功能。使用自定义维度和自定义指标需遵循如下规则：

a. 在同一个事件中需携带不同的自定义维度和自定义指标时，各个自定义维度和自定义指标的key不应相同，否则会造成相同key对应的value被覆盖的情况,正确的使用方法是分别使用key为cd1、cd2...cd25来存储不同的维度名称，自定义指标同理。

举例1. 假设在app中存在页面名称为首页的页面，用户可在该页面领取任务奖励。
数据分析需求：当首页被打开后在页面浏览数据上报时，携带打开这个页面的用户账号id、昵称。
正确的方案是：

MzanalyticsMybmw.trackPageView({
                       "dt": "首页", 
                     "CustomDimMetrics": {
	                      "cd1":"ID88888", //使用cd1 传入用户Id
	                      "cd2": "小明机器人"   //使用cd2 传入用户昵称              
                     }  
    });

b. 不同事件上报不同的自定义维度和自定义指标时，各个自定义维度和自定义指标的key不应相同，若都使用同一个key，所有同key的自定义维度数据会和不同事件的数据关联在一起，造成运营分析困难。

举例2：假设在app的首页中用户可以在完成特定任务后，点击任务箱领取按钮获得奖励。

数据分析需求：用户既需要监听首页的浏览事件，在页面浏览数据上报时携带用户账号Id、昵称，也需要监听首页领取奖励按钮的点击事件，并同时上报已领取的任务箱名称和任务箱的个数。
正确的方案是：用户账号Id、昵称和任务箱名称采用不同的自定义维度key，自定义指标同理。

//页面埋点部分参考举例1的代码示例，下方仅提供按钮点击事件的埋点代码示例
MzanalyticsMybmw.trackEvent({
                   "ec": "领取奖励",
                   "ea": "Click",
                   "el": "任务箱领取奖励",
                   "ev": "1",
                 "CustomDimMetrics": {
                   "cd3": "完成资料填写任务箱",  //由于用户Id和昵称已占用cd1和cd2的key，为保证数据正确，应采用cd3
                   "cm2": "2" // 此处代表任务箱的个数
			 }
       });

c. 所有的页面浏览、自定义事件、高级事件中都需要携带相同的信息时，可设置全局的自定义维度和自定义指标，该全局设置在单次app的生命周期中生效（参考文档部分：4 设置自定义维度和自定义指标的相关方法(可选)）

2.0 开启调试日志

说明：该api是用于输出秒针分析sdk的调试日志，默认关闭。建议在集成调试时打开该开关以测试集成效果。
接口定义：

static Future<void> setEnabled(bool enabled)

参数说明：

参数	类型	说明
enabled	bool	传true打开日志调试开关；默认值为false，关闭日志调试开关（必填）

 示例代码：      
 MzanalyticsLog.enabled = true;

3 页面自动监听(可选，可与1.2页面监测二选一) #

需使用navigatorObservers方法来实现页面的自动监听功能。
说明: 必须在 sdkconfig.xml的开关配置文件中，将值设置为true才能启用页面自动监听功能。

3.1 注册页面监听

首先需要在启动页的`main.dart`中的主`Widget build(BuildContext context)`方法中按如下方式添加观察者对象方法：`MZNavigationHistoryObserver()`。

示例如下：

@override
  Widget build(BuildContext context) {

    return new MaterialApp(
      debugShowCheckedModeBanner: false,
      title: "首页",
      theme: ThemeData(
        primaryColor: Color(0xff303030),
        scaffoldBackgroundColor: Color(0xffebebeb),
        cardColor: Color(0xff393a3f)
      ),
      routes: routeTable,
      home: LoadingPage(),
      navigatorObservers:[MZNavigationHistoryObserver()],
       
      
    );
  }

3.2 页面跳转示例代码

在App中需要监听跳转页面名称的`Navigator.of`方法中需传入对应的页面名称参数。

示例方法1：

Navigator.of(_ctx).push(MaterialPageRoute(settings: RouteSettings(name: "首页"), builder: (_ctx) => page));

示例方法2：

Navigator.of(_ctx).pushNamed("首页");

4 设置自定义维度和自定义指标的相关方法(可选)

4.1 设置自定义维度cd

说明：若需要在用户每一个触发的页面、自定义事件、高级事件中携带同一个维度，调用该api实现上述三类事件中携带全局自定义维度cd。
作用域: 仅在单次的app生命周期中生效。

 接口定义：

  Future<void> setCd(String cdKey, String cdValue)

参数说明：

参数	类型	说明	是否必填
cdKey[1~25]	String	自定义维度key( 取值范围cd[1-25] )	必填
cdValue	String	自定义维度value	必填

示例代码：

try {
 MzanalyticsMybmw.setCd("cd1", "ID88888");//携带用户账号ID维度
} on PlatformException {}

4.2 设置自定义指标cm

说明：如果需要在用户每一个触发的页面、自定义事件、高级事件中携带某个指标，调用该api实现上述三类事件中携带全局自定义指标cm。
作用域: 仅在单次的app生命周期中生效。

接口定义：

  Future<void> setCm(String cmKey, String cmValue)

参数说明：

参数	类型	说明	是否必填
cmKey[1~25]	String	自定义指标key( 取值范围cm[1-25] )	必填
cmValue	String类型的数值	自定义指标value	必填

示例代码：

try {
  MzanalyticsMybmw.setCm("cm1", "1001");
} on PlatformException {}

4.3 删除App缓存中的自定义维度cd

说明：调用该接口删除app缓存中的自定义维度cd[1~25]。

接口定义：

  Future<void> deleteCd(var cdKey)

参数说明：

参数	类型	说明	是否必填
cdkey[1~25]	String	自定义维度key( 取值范围cd[1-25] )	必填

示例代码：

try {
  MzanalyticsMybmw. deleteCd("cd1");
} on PlatformException {}

4.4 删除App缓存中的自定义维度cm

说明：调用该接口删除app缓存中的自定义指标cm[1~25]。

接口定义：

  Future<void> deleteCm(var cmKey)

参数说明：

参数	类型	说明	是否必填
cmKey[1~25]	String	自定义指标key( 取值范围cm[1-25] )	必填

示例代码：

try {
  MzanalyticsMybmw.deleteCm("cm1");
} on PlatformException {}

4.5 获取自定义维度cd和自定义指标cm集合

说明：调用该接口获取app缓存中的自定义维度cd和自定义指标cm。

接口定义：

Future<Map> getCdAndCm()    


示例代码：

try {
   Map map = MzanalyticsMybmw.getCdAndCm();
} on PlatformException {}

1. Preparations 🍭 #

1. Version restrictions #

Flutter SDK: >=1.17.0.
Xcode version: >=12.0.
MZAnalyticsIOSSDK applies to iOS 9-iOS 14.0, please set iOS Deployment Target to iOS 9.0,.
MZAnalyticsAndroidSDK is applicable to devices with Android 2.3.3 (API Level 10) and above.

Suggest: #

It is recommended that the SDK initialization method be executed after obtaining the device ID, storage and other permissions. If the SDK initialization method is placed before authorization, it may affect the accuracy of data such as activation attribution.

2. Flutter project add dependency #

Add mzanalytics_mybmw to pubspec.yaml reference.

dependencies:
mzanalytics_mybmw: ^${latestVersion}

Run flutter pub get in flutter project

3. Integration Preparation #

3.1 Apply for AppId for the application

Create an application on the https://tongji.cn.miaozhen.com website, You will get a string of random site id starting with "dc-", which is used to uniquely identify one of your apps.

3.2 AppId description

appId is the unique identifier for application tracking, which can be obtained from Site-->Site Information in the https://tongji.cn.miaozhen.com website.

3.3 The configuration when the customer needs to obtain the OAID on the Android platform

**Note: Only support OAID acquisition of MSA SDK 1.0.25 version. ** Whether to configure or not can be determined according to the customer's personal needs. If configured, Miaozhen Analysis SDK can collect OAID; if not configured, OAID cannot be acquired. Please follow the MSA SDK integration method recommended by the Mobile Security Alliance official website. Link to the official website of the Mobile Security Alliance: https://msa-alliance.cn/col.jsp?id=120

3.4 Android SDK permission configuration #

The following permissions are configured according to the actual needs of customers:

Permission	Permission description	Optional	Impact of non-authorization
INTERNET	Allow program networking	Required	SDK cannot send data
ACCESS_NETWORK_STATE	Allow detection of network connection status	Optional	SDK does not detect network status, directly sends data
READ_PHONE_STATE	Allow access to the unique identification information of the mobile device	Optional	SDK cannot obtain the device ID
ACCESS_WIFI_STATE	Allow to read WiFi state changes	Optional	Affect the data sending frequency of the data SDK
READ_EXTERNAL_STORAGE	Allows to read the data stored on the SD card	Mandatory option	Affects the SDK to read the CID of the unique user and the historical data of the sending failure
WRITE_EXTERNAL_STORAGE	Allows writing information such as the CID of the unique user to the SD card	Required option	Affects the SDK storage of the CID of the unique user and the writing of failed data

Sample code:

<!-- Network permissions -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Network status related permissions -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- Mobile phone information related permissions -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- SD card read and write permissions -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

4. Running environment configuration #

4.1 iOS operating environment configuration

a. cd to the iOS project directory.
b. Execute `pod install` on the terminal.
c. Open `Runner.xcworkspace`, find sdkconfig.xml` in `Pods->Development->mzanalytics_mybmw->..->Classes, and drag it to the project Runner.

4.2 Android operating environment configuration

a. Enter the android project directory `app/src/main`.
b. Copy the assets folder (including sdkconfig.xml and supplierconfig.json) to the `main` directory.
c. Add attributes to the application tag (appkey is a pure number):
     <meta-data
       android:name="com.miaozhen.mzsdk.appKey"
       android:value="xxxx" />
     <meta-data
       android:name="com.miaozhen.mzsdk.channelId"
       android:value="xxxxx" />

Second, Miaozhen analysis SDK usage #

Introducing header files in flutter code:

import'package:mzanalytics_mybmw/mzanalytics_mybmw.dart';

1 Call example #

1.1 Initialize SDK (required embedding point)

Note: Replace xxxx with the actual AppId when using it (iOS is passed in in the api, Android needs to be configured in the application tag)

Interface definition:

 Future<void> appid(String aid)

Parameter Description:

Parameter	Type	Description	Is it required
aid	String	is the site id when creating the site	required

Sample code:
//Create an application in the https://tongji.cn.miaozhen.com website, the site id is dc-2814; pass 2814 into the interface

MzanalyticsMybmw.appid("2814");

1.2 Page Browsing (Optional burying point, and page automatic monitoring program can choose one)

Description:

a. Used to monitor page browsing behavior. After adding the following code to the page startup method that needs to be monitored, the user's page browsing behavior can be collected;

b. If you need to carry more information when reporting page browsing data, you can use custom dimensions and custom indicators. [For specific usage rules, see 1.9 How to use custom dimensions and custom indicators in the document]

Interface definition:

Future<void> trackPageView(Map parameter)

Parameter Description:

Parameter	Type	Description	Is it required
dt	String	The name of the page to be monitored	Required
customDimMetrics	Map	Custom dimension and custom metric collection name	Optional, when there is no need to carry custom dimensions and custom metrics in the business scenario, do not write customDimMetrics

Description of custom parameters to be passed in customDimMetrics:

Parameter	Type	Description	Required
cd[1~25]	String	Custom dimensions, up to 25	Optional
cm[1~25]	String type value	Custom indicators, up to 25	Optional

Sample code that does not pass custom dimensions and custom metrics:
MzanalyticsMybmw.trackPageView({"dt": "Homepage"});//page name, such as homepage


Sample code for passing custom dimensions and custom metrics:
 MzanalyticsMybmw.trackPageView({
                   "dt": "Home",
                 "CustomDimMetrics": {
                   "cd1":"ID88888",//The name of the custom dimension 1 to be counted, such as the user Id who browses the page
                   "cd2": "Xiaoming Robot", //The name of the custom dimension 2 to be counted, such as the name of the user who browses the page
                   "cm1": "1"//The value of the custom indicator to be counted, such as the number of users is 1
                 }
});

1.3 Custom event (optional buried point)

Description: a. For the interaction between the user and the App, you can add custom event codes for statistics, and add the following codes to the click methods of buttons or other controls that need to be customized; b. If you need to carry more information when reporting custom event data, you can use custom dimensions and custom indicators. [For specific usage rules, see 1.9 How to use custom dimensions and custom indicators in the document]

Interface definition:

Future<void> trackEvent(Map parameter)

Parameter Description:

| Parameter | Type | Description | Is it required | | ------------- | --------- | ---------------- |-------- -| | ec | String | Event category |Required | | ea | String | Event Action | Optional | | el | String | Event label | Optional | | ev | String type value | Event value | Optional || customDimMetrics | Map | Custom dimension and custom metric collection name | Optional, when there is no custom dimension and custom metric, just leave customDimMetrics alone |

Description of custom parameters to be passed in customDimMetrics:

Parameter	Type	Description	Required
cd[1~25]	String	Custom dimensions, up to 25	Optional
cm[1~25]	String type value	Custom indicators, up to 25	Optional

 Sample code that does not pass custom dimensions and custom metrics:
MzanalyticsMybmw.trackEvent({
               "ec":"Receive rewards",//The name of the event category to be counted, such as receiving rewards
               "ea":"Click",//The name of the event action to be counted, such as Click
               "el":"task box to receive rewards", //event labels that need to be counted, such as task box to receive rewards and punishments
               "ev": "10" //The value of the event to be counted, such as 10
             });
             
Sample code for passing custom dimensions and custom metrics:
MzanalyticsMybmw.trackEvent({
                   "ec":"Receive reward",
                   "ea":"Click",
                   "el":"Task box to receive rewards",
                   "ev": "1",
                 "CustomDimMetrics": {
                   "cd3": "LoginBox", //The name of the custom dimension to be counted, such as the name of the task box
                   "cm2": "2" //Custom indicator values to be counted, such as the number of open task boxes, total 2
                 }
                 });

1.4 Advanced event (optional buried point)

Description: a. Advanced event statistics codes can count user interaction events with more dimensions and indicators. Users can set the dimensions and indicators to be counted according to statistical business needs.

b. If you need to carry more information when reporting advanced event data, you can use custom dimensions and custom indicators. [For specific usage rules, see 1.9 How to use custom dimensions and custom indicators in the document]

Interface definition:

Future<void> trackSiteCustomEvent(Map parameter)

Parameter Description:

Parameter	Type	Description	Required
customEvent	Map	Contains advanced event id, advanced event dimensions, and the number of indicators are subject to the actual advanced event created in the system	Required
customDimMetrics	Map	Custom dimension and custom metric collection name	Optional, if there is no custom dimension and custom metric, customDimMetrics can not be passed

Description of advanced event parameters to be passed in CustomEvent:

Parameter	Type	Description	Required
caid	Int	Advanced event id	Required
cal[1~20]	String	Advanced event dimensions, up to 20	Optional
cav[1~20]	Int	Advanced event indicators, up to 20	Optional

Description of custom parameters to be passed in customDimMetrics:

Parameter	Type	Description	Required
cd[1~25]	String	Custom dimensions, up to 25	Optional
cm[1~25]	Int	Custom indicators, up to 25	Optional

 Sample code without passing custom dimensions and metrics:
 MzanalyticsMybmw.trackSiteCustomEvent({
                 "CustomEvent": {
                   "caid": "1", //The advanced event Id to be counted needs to be obtained after the advanced event is configured in the Miaozhen analysis system. For example, it means the registered event with the advanced event ID of 1.
                   "cal1": "2020/01/10", //Advanced event dimension 1 to be counted, such as registration time
                   "cal2": "Beijing",//Advanced event dimension 2 to be counted, such as registered location
                   "cav1": "20" //Advanced event indicators to be counted, such as the age of the user who triggered the registration event
                 }
               });


Sample code for passing custom dimensions and metrics:
 MzanalyticsMybmw.trackSiteCustomEvent({
                 "CustomEvent": {
                   "caid": "1",
                   "cal1": "2020/01/10",
                   "cal2": "Beijing",
                   "cav1": "20"
                 },
                 "CustomDimMetrics": {
                   "cd1": "ID88888",//Custom dimensions to be counted, such as the user Id that triggered the registration event
                   "cm1": "1"//Custom metrics to be counted, such as the number of users triggering advanced events 1
                 }
               });

1.5 Heartbeat event (optional buried point)

Note: This event can be buried when the user exits the App or page, and used to calculate more accurate App usage time.

Interface definition:

 Future<void> trackPulse()

Parameter description: None

Sample code:

 MzanalyticsMybmw.trackPulse();

1.6 Get visitor id (optional call api)

Note: The visitor id is the id of the unique user identified by Miaozhen Analysis. This interface can be used by customers to obtain the cid generated by the Miaozhen Analysis SDK.

Interface definition:

  Future<String> getCid()

Parameter description: None

Sample code:

 MzanalyticsMybmw.getCid();

1.7 DeepLink (optional buried point)

Note: It is used to count the monitoring of deeplink links after Miaozhen analysis advertising parameters have been added. If Miaozhen advertising parameters are not added, the behavior of ordinary deeplink links lifting the app will not be counted.

 Interface definition:
 static Future<void> onDeepLinkReceived(String url)

Parameter Description:

Parameters	Type	Description
url	String	URL received after deeplink redirection (required)

 Sample code:
//deeplink
  MzanalyticsMybmw.onDeepLinkReceived(url);

url example:

mltsite://event/page/view/last?name=ceshi&age=30&mz_ca=2220134&mz_sp=35790

Format specification:
scheme://host/path?key1=value1&key2=value2&mz_ca=2220134&mz_sp=35790

Description:
a. Question mark? Customers can define by themselves in front;
b. After the question mark, the key and value must be connected with =, and the different key-value must be connected with &;
c. Both mz_ca and mz_sp are classified as deeplink traffic, otherwise they are classified as ordinary traffic;
d. The legal mz_ca is 7 digits, and the legal mz_sp is 5 digits.

1.8 SDKConfig permission configuration (configure yourself according to business needs)

The sdkconfig.xml in the project is the switch configuration file. Configure the switches for idfa, imei, oaid (optional, if you need to obtain the MSA SDK as recommended by the Mobile Security Alliance), adid, and autotrackpage configuration switches.

a. When the value of isRequired in the idfa, imei, oaid, and adid configuration is set to true, get the above id;
b. When the value of isRequired in the idfa, imei, oaid, and adid configuration is set to false, the above id will not be obtained;
c. When you need to automatically monitor the page, please set the value of autotrackpage to false, and when you need to automatically monitor the page, set the value to true;
d. When the page needs to be automatically monitored, but the automatic monitoring of a specific page A needs to be filtered, modify the value corresponding to the manualtrackpage to its page title. After setting, page A will not be automatically monitored. If there are multiple pages that do not need to be automatically monitored, just enter multiple page titles in the value section, and separate multiple page titles with ",".

Note: When filling in the page title that does not need to be automatically monitored, the page title must not contain "," under the Chinese input method, otherwise it will cause incorrect filtering.

1.9 How to use custom dimensions and indicators

You can use the custom dimension and custom indicator functions provided by Miaozhen Analysis when you need to carry additional information when reporting page browsing, custom events and advanced event data. Use custom dimensions and custom indicators to follow the following rules:

a. When different custom dimensions and custom indicators need to be carried in the same event, the key of each custom dimension and custom indicator should not be the same, otherwise the value corresponding to the same key will be overwritten , The correct way to use it is to use keys as cd1, cd2...cd25 to store different dimension names, the same is true for custom indicators.

Example 1. Assuming that there is a page whose name is the homepage in the app, the user can receive task rewards on this page. Data analysis requirements: When the page browsing data is reported after the homepage is opened, carry the user account id and nickname that opened the page. The correct solution is:

MzanalyticsMybmw.trackPageView({ "dt": "Home", "CustomDimMetrics": { "cd1":"ID88888", //Use cd1 to pass in user Id "cd2": "Xiaoming Robot" //Use cd2 to pass in user nickname } });

b. When different events report different custom dimensions and custom indicators, the key of each custom dimension and custom indicator should not be the same. If they all use the same key, all custom dimension data with the same key will be It is associated with data from different events, which makes operational analysis difficult.

Example 2: Suppose that on the homepage of the app, the user can click the task box to receive a reward after completing a specific task.

Data analysis requirements: Users need to monitor the browsing events of the homepage, carry the user ID and nickname when reporting the page browsing data, and also need to monitor the click event of the reward button on the homepage, and report the received task box name and task box at the same time Number. The correct solution is: the user account ID, nickname, and task box name use different custom dimension keys, and the custom indicators are the same.

//Refer to the code example of example 1 for the embedded point part of the page, and only the code example of the embedded point for button click events is provided below
MzanalyticsMybmw.trackEvent({
                   "ec":"Receive reward",
                   "ea":"Click",
                   "el":"Task box to receive rewards",
                   "ev": "1",
                 "CustomDimMetrics": {
                   "cd3": "TaskBox1", //Since the user ID and nickname have occupied the keys of cd1 and cd2, cd3 should be used to ensure the correct data
                   "cm2": "2" // This represents the number of character boxes

} });

c. When all page views, custom events, and advanced events need to carry the same information, you can set global custom dimensions and custom indicators. The global settings take effect in the life cycle of a single app (refer to the document section ：4 Related methods for setting custom dimensions and custom indicators (optional))

2.0 Enable debug log

Description: This api is used to output the debug log of the second hand analysis SDK, which is closed by default. It is recommended to turn on this switch during integration debugging to test the integration effect.

Interface definition:

static Future

Parameter Description:

Parameters	Type	Description
enabled	bool	Pass true to turn on the log debugging switch; the default value is false, turn off the log debugging switch (required)

  Sample code:
  MzanalyticsLog.enabled = true;

3 page automatic monitoring (optional, can choose one of 1.2 page monitoring) #

Need to use the navigatorObservers method to realize the automatic monitoring function of the page. Explanation: You must set the value to true in the switch configuration file of sdkconfig.xml to enable automatic page monitoring.

3.1 Register page monitoring

First, you need to add an observer object method in the main `Widget build(BuildContext context)` method in the `main.dart` of the startup page as follows: `MZNavigationHistoryObserver()`.

Examples are as follows:

@override
  Widget build(BuildContext context) {

    return new MaterialApp(
      debugShowCheckedModeBanner: false,
      title: "Home",
      theme: ThemeData(
        primaryColor: Color(0xff303030),
        scaffoldBackgroundColor: Color(0xffebebeb),
        cardColor: Color(0xff393a3f)
      ),
      routes: routeTable,
      home: LoadingPage(),
      navigatorObservers:[MZNavigationHistoryObserver()],
       
      
    );
  }

3.2 Page Jump Sample Code

The `Navigator.of` method that needs to monitor the jump page name in the App needs to pass in the corresponding page name parameter.

Example method 1:

Navigator.of(_ctx).push(MaterialPageRoute(settings: RouteSettings(name: "Home"), builder: (_ctx) => page));

Example method 2:

Navigator.of(_ctx).pushNamed("Home");

4.1 Set custom dimension cd

Note: If you need to carry the same dimension in each triggered page, custom event, and advanced event of the user, call this api to carry the global custom dimension cd in the above three types of events. Scope: Only effective in a single app life cycle.

 Interface definition:

  Future<void> setCd(String cdKey, String cdValue)

Parameter Description:

Parameter	Type	Description	Required
cdKey[1~25]	String	Custom dimension key (value range cd[1-25])	Required
cdValue	String	Custom dimension value	Required

Sample code:

try {
 MzanalyticsMybmw.setCd("cd1", "ID88888");
} on PlatformException {}

4.2 Set custom indicator cm

Note: If you need to carry a certain indicator in each triggered page, custom event, and advanced event of the user, call this api to carry the global custom indicator cm in the above three types of events. Scope: Only effective in a single app life cycle.

Interface definition:

  Future<void> setCm(String cmKey, String cmValue)

Parameter Description:

Parameter	Type	Description	Required
cmKey[1~25]	String	Custom indicator key (value range cm[1-25])	Required
cmValue	String type value	Custom indicator value	Required

Sample code:

try {
  MzanalyticsMybmw.setCm("cm1", "1001");
} on PlatformException {}

4.3 Delete the custom dimension cd in the App cache

Description: Call this interface to delete the custom dimension cd[1~25] in the app cache.

Interface definition:

  Future<void> deleteCd(var cdKey)

Parameter Description:

Parameter	Type	Description	Required
cdkey[1~25]	String	Custom dimension key (value range cd[1-25])	Required

Sample code:

try {
  MzanalyticsMybmw. deleteCd("cd1");
} on PlatformException {}

4.4 Delete the custom dimension cm in the App cache

Description: Call this interface to delete the custom indicator cm[1~25] in the app cache.

Interface definition:

  Future<void> deleteCm(var cmKey)

Parameter Description:

Parameter	Type	Description	Required
cmKey[1~25]	String	Custom indicator key (value range cm[1-25])	Required

Sample code:

try {
  MzanalyticsMybmw.deleteCm("cm1");
} on PlatformException {}

4.5 Get custom dimension cd and custom indicator cm collection

Description: Call this interface to get the custom dimension cd and custom indicator cm in the app cache.

Interface definition:

Future<Map> getCdAndCm()

Sample code:

try {
   Map map = MzanalyticsMybmw.getCdAndCm();
} on PlatformException {}

mzanalytics_mybmw 0.3.2 mzanalytics_mybmw: ^0.3.2 copied to clipboard

Metadata

秒针分析SDK部署指南(Flutter测试版本） #

一、准备工作 🍭 #

1. 版本限制 #

建议： #

2. Flutter项目添加依赖 #

3. 集成准备 #

3.1 为应用申请AppId

3.2 AppId说明

3.3 客户需在Android 平台上获取OAID时的配置

3.4 Android SDK 权限配置 #

4. 运行环境配置 #

4.1 iOS运行环境配置

4.2 Android运行环境配置

二、秒针分析SDK使用 #

flutter代码中引入头文件:

1 调用示例 #

1.1 初始化SDK (必选埋点)

1.2 页面浏览 (可选埋点，与页面自动监听方案可二选一)

1.3 自定义事件 (可选埋点)

1.4 高级事件 (可选埋点)

1.5 心跳事件 (可选埋点)

1.6 获取访客id（可选调用api，不用于sdk统计数据）

1.7 DeepLink(可选埋点)

1.8 SDKConfig权限配置(根据业务需求自行配置)

1.9 自定义维度和指标的使用方法

2.0 开启调试日志

3 页面自动监听(可选，可与1.2页面监测二选一) #

3.1 注册页面监听

3.2 页面跳转示例代码

4 设置自定义维度和自定义指标的相关方法(可选)

4.1 设置自定义维度cd

4.2 设置自定义指标cm

4.3 删除App缓存中的自定义维度cd

4.4 删除App缓存中的自定义维度cm

4.5 获取自定义维度cd和自定义指标cm集合

1. Preparations 🍭 #

1. Version restrictions #

Suggest: #

2. Flutter project add dependency #

3. Integration Preparation #

3.1 Apply for AppId for the application

3.2 AppId description

3.3 The configuration when the customer needs to obtain the OAID on the Android platform

3.4 Android SDK permission configuration #

4. Running environment configuration #

4.1 iOS operating environment configuration

4.2 Android operating environment configuration

Second, Miaozhen analysis SDK usage #

Introducing header files in flutter code:

1 Call example #

1.1 Initialize SDK (required embedding point)

1.2 Page Browsing (Optional burying point, and page automatic monitoring program can choose one)

1.3 Custom event (optional buried point)

1.4 Advanced event (optional buried point)

1.5 Heartbeat event (optional buried point)

1.6 Get visitor id (optional call api)

1.7 DeepLink (optional buried point)

1.8 SDKConfig permission configuration (configure yourself according to business needs)

1.9 How to use custom dimensions and indicators

2.0 Enable debug log

3 page automatic monitoring (optional, can choose one of 1.2 page monitoring) #

3.1 Register page monitoring

3.2 Page Jump Sample Code

4 Related methods for setting custom dimensions and custom indicators (optional)

4.1 Set custom dimension cd

4.2 Set custom indicator cm

4.3 Delete the custom dimension cd in the App cache

4.4 Delete the custom dimension cm in the App cache

4.5 Get custom dimension cd and custom indicator cm collection

← Metadata

Publisher

Metadata

License

Dependencies

More

mzanalytics_mybmw 0.3.2
mzanalytics_mybmw: ^0.3.2 copied to clipboard