秒针分析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: ^0.2.0

在flutter项目中运行 flutter pub get


3. 集成准备

3.1 为应用申请AppID

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

3.2 AppID说明

 appId为应用追踪的唯一标识,在站点信息内获取。

3.3 Android SDK 需获取OAID的配置

说明:可依据客户个人需求决定是否配置。若配置,秒针分析SDK可采集OAID信息;若不配置,则不能采集OAID信息。

在项目build.gradle的defaultConfig添加如下配置:

ndk {
       abiFilters 'armeabi-v7a', 'x86', 'arm64-v8a', 'x86_64', 'armeabi'
    }
    packagingOptions {
        doNotStrip "*/armeabi-v7a/*.so"
        doNotStrip "*/x86/*.so"
        doNotStrip "*/arm64-v8a/*.so"
        doNotStrip "* /x86_64/*.so"
        doNotStrip "armeabi.so"
    }
使用插件,android会增加两步配置:
    第一步:拷贝msa_mdid_1.0.13到项目中,与app目录同级别
    第二步:在setting.gradle中添加:include ':msa_mdid_1.0.13'
将assets目录文件导入目标项目的assets。其中supplierconfig.json文件需修改里边对应内容,特别是需要设置 appid 的部分。需要设置 appid 的部分需要去对应厂商的应 用商店里注册自己的app。

3.4 Android SDK权限配置

常规权限:

权限用途
INTERNET允许程序联网和上报监测数据。
ACCESS_NETWORK_STATE允许检测网络连接状态,在网络异常状态下避免数据发送,节省流量和电量。
READ_PHONE_STATE允许访问手机设备的信息,通过获取的信息来唯一标识用户。
ACCESS_WIFI_STATE允许读取WiFi相关信息,在合适的网络环境下更新配置。
READ_EXTERNAL_STORAGE允许读取SD卡上存储的相关ID信息 。
WRITE_EXTERNAL_STORAGE允许写入相关ID信息到SD卡上。
示例代码:

<!-- 网络权限 -->
<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 (Android需在application标签中配置)

接口定义:

 Future<void> appid(String aid)

参数说明:

参数类型说明
aidString网站创建站点时的站点id为您的AppId。
示例代码 :   
//在 https://tongji.cn.miaozhen.com 网站中创建一款应用,站点id为dc-2814;将2814传入该接口

MzanalyticsMybmw.appid("2814");
    

1.2 页面监测 (可选埋点)

说明:用于采集页面浏览事件,在需要监测的页面启动方法中添加如下代码后,即可采集用户的页面浏览行为。

接口定义:

Future<void> trackPageView(Map parameter)

参数说明:

参数类型说明是否必填
dtString页面名称必填

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

参数类型说明是否必填
cd1~25String自定义维度选填
cm1~25String自定义指标选填
不传递自定义维度和指标的示例代码:
MzanalyticsMybmw.trackPageView({"dt": "首页"});


传递自定义维度和指标的示例代码:
MzanalyticsMybmw.trackPageView({
                   "dt": "首页",
                 'CustomDimMetrics': {
                   "cd1": "账号名称",
                   "cm1": "数量1"
                 } 
});

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

说明:用户与App的交互动作,可添加自定义事件代码进行统计,在需要自定义埋点的按钮或其他控件的点击方法中,添加如下代码。

接口定义:

Future<void>  trackEvent(Map parameter)

参数说明:

参数类型说明是否必填
ecString事件分类必填
eaString事件动作选填
elString事件标签选填
evString事件价值选填

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

参数类型说明是否必填
cd1~25String自定义维度选填
cm1~25String自定义指标选填
 不传递自定义维度和指标的示例代码:
MzanalyticsMybmw.trackEvent({
               "ec": '点击热⻔banner',
               "ea": 'Click',
               "el": '点击',
               "ev": '0',
             });
             
传递自定义维度和指标的示例代码:
MzanalyticsMybmw.trackEvent({
                   "ec": '点击热⻔banner',
                       "ea": 'Click',
                       "el": '点击',
                      "ev": '0',
                 'CustomDimMetrics': {
                   "cd1": "账号名称",
                   "cm1": "数量1"
                 }
                 });

1.4 高级自定义事件 (可选埋点)

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

接口定义:

Future<void>  trackSiteCustomEvent(Map parameter) 

参数说明:

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

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

参数类型说明是否必填
caidString高级事件id必填
cal1~20String高级事件维度选填
cav1~20String高级事件指标选填

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

参数类型说明是否必填
cd1~25String自定义维度选填
cm1~25String自定义指标选填
 不传递自定义维度和指标的示例代码:
 MzanalyticsMybmw.trackSiteCustomEvent({
                 'CustomEvent': {
                   "caid": "1",
                   "cal1": "2020/01/10",
                   "cal2": "15728749249",
                   "cal3": "北京",
                   "cav1": "2"
                 }
               });
传递自定义维度和指标的示例代码:
 MzanalyticsMybmw.trackSiteCustomEvent({
                 'CustomEvent': {
                   "caid": "1",
                   "cal1": "2020/01/10",
                   "cal2": "15728749249",
                   "cal3": "北京",
                   "cav1": "2"
                 },
                 'CustomDimMetrics': {
                   "cd1": "点击信用卡",
                   "cd2": "查看商品详情",
                   "cm1": "点击信用卡总用户数",
                   "cm2": "查看商品详情总用户数"
                 }
               });
               

备注:

高级事件ID必传。     
cal最多20个,名称为cal1~20。       
cav最多20个,名称为cav1~20。       
cd最多25个,名称为cd1~25。     
cm最多25个,名称为cm1~25。     

实际使用时将高级事件维度、高级事件指标、自定义维度、自定义指标替换为实际回传值。

1.5 心跳事件 (可选埋点)

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

接口定义:

 Future<void> trackPulse()
     

参数说明: 无

示例代码:

 MzanalyticsMybmw.trackPulse();

1.6 获取访客id(设备唯一ID)

说明:访客id是秒针分析标识唯一用户的id,该接口多用于客户测试场景。

接口定义:

  Future<String> getCid() 

参数说明: 无

示例代码:

 MzanalyticsMybmw.getCid();

1.7 获取oaid(只对Android有效)

说明:oaid是msa sdk集成后方能获取的标识设备的id,该接口多用于客户测试场景。

接口定义:

 Future<String> getOaid()

参数说明:无

示例代码:
MzanalyticsMybmw.getOaid()  

说明:用于统计点击秒针分析广告后吊起app的行为数据,须在iOS的appDelegate.m页面中配置deeplink相关代码。

 接口定义:
+(void)handleOpenURL:(NSURL *)url;

参数说明:

参数类型说明
urlNSURL回调接收到的url (必填)
示例代码:

在AppDelegate.m的deeplink系统回调中现实本方法, 根据项目配置如下:
/**DeepLink */
-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url 
    options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options{
     
     [MLTSiteManager  handleOpenURL:url];
      
    return YES;
    }
    
/**UniversalLinks */
-(BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler{
      
    [MLTSiteManager handleOpenURL:userActivity.webpageURL];          
     
    return YES;
    }
    

说明:请在Android原生页面配置完成。修改AndroidManifest.xml文件。在接受deeplink唤起的activity配置中添加如下代码:

<intent-filter >
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
        <data
            android:host="bj"
          android:pathPrefix="/site"
          android:scheme="miaozhen" />
</intent-filter>
唤起链接说明
示例:
    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
说明:
    1、问号?前面客户可以自己定义
    2、问号后面key和value连接必须用=,不同key-value拼接必须用&
    3、同时存在mz_ca和mz_sp归为deeplink流量,否则归为普通流量
    4、mz_ca合法是7位,mz_sp合法是5位 

Android 唤起事件Activity的onCreate()方法中初始化如下方法:

//SDK 配置相关
MzConfig config = new MzConfig();
//调试时设置log开关
config.setDebugMode(true);
//SDK初始化
MzSiteSDK mzSiteSDK =     MzSiteSDK.getInstance(getApplicationContext(),config,getIntent());

备注:如果想完整启动app,建议添加到启动页面。

2.0 SDKConfig权限配置

项目中 sdkconfig.xml是开关配置文件。为 idfa、imei、oaid、adid、autotrackpage配置开关。

  • 当设置isRequired字段的value,字段取值为true时,开启获取;
  • 当设置isRequired字段的value,字段取值为false时,不获取。
  • 当需配置不需要自定动监听的页面列表时,修改manualtrackpage对应的value为其页面标题,设定后会自动过滤这些页面的监听,若有多个页面不需要自动监听,则在value部分输入多个页面标题即可,多个页面标题之间用“、”分隔。

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

3.0 页面监听上报

要使用`navigatorObservers`方法来监听页面,实现自动上报。

3.1.注册页面监听

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

示例如下:
@override
  Widget build(BuildContext context) {

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

3.2 页面跳转示例代码:

在App中需要监听跳转页面title的`Navigator.of`方法中需传入对应的name参数, name即为需要采集的title名称。 

  示例方法1:

  Navigator.of(_ctx).push(MaterialPageRoute(settings: RouteSettings(name: "$pageTitle"), builder: (_ctx) => page));
示例方法2:

Navigator.of(_ctx).pushNamed("$page");

3.3 设置自定义维度和自定义指标的相关方法

3.3.1 设置自定义维度cd

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

 接口定义:

  Future<void> setCd(String cd_key, String cd_value)

参数说明:

参数类型说明是否必填
cd_key1~25String自定义事件维度key( 取值范围cd1-25 )必填
cd_value1~25String自定义事件指标value必填
示例代码:

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

3.3.2 设置自定义指标cm

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

接口定义:

  Future<void> setCm(String cm_key, String cm_value)

参数说明:

参数类型说明是否必填
cm_key1~25String自定义事件指标key( 取值范围:cm1-25 )必填
cm_value1~25String自定义事件指标value必填
示例代码:

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

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

说明:调用该接口删除app缓存中的自定义维度cd1~25。

接口定义:

  Future<void> deleteCd(var cd_key)    

参数说明:

参数类型说明是否必填
cd_key1~25String自定义事件指标key( 取值范围:cd1-25 )必填
示例代码:

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


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

说明:调用该接口删除app缓存中的自定义指标cm1~25。

接口定义:

  Future<void> deleteCm(var cm_key)    

参数说明:

参数类型说明是否必填
cm_key1~25String自定义事件指标key( 取值范围:cm1-25 )必填
示例代码:

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



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

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

接口定义:

Future<Map> getCdAndCm()    
示例代码:

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




Libraries

mzanalytics_android
mzanalytics_ios
mzanalytics_mybmw