神策 sensors_analytics_flutter_plugin 插件,封装了神策 Android 和 iOS SDK 常用 API,使用此插件,可以在 Flutter 开发的 App 中完成埋点的统计和上报。

1. 集成神策分析 SDK Flutter 插件

在 Flutter 项目的 pubspec.yaml 文件中 dependencies 里面添加 sensors_analytics_flutter_plugin 依赖

dependencies:  
  # 添加神策 flutter plugin 
  sensors_analytics_flutter_plugin: ^2.0.1
CODE

执行 flutter packages get 命令安装插件

flutter packages get
CODE

2. iOS 端

2.1. 集成神策分析 iOS SDK

在执行 flutter packages get 命令的时候,会自动在 ios 目录下执行 pod install 命令进行 iOS SDK 的集成。如果您在使用 iOS SDK 时,发现找不到头文件,可以到 iOS 目录下手动执行一下 pod install 命令

cd ios && pod install && cd ../
CODE

2.2. 初始化神策分析 SDK

2.2.1. 获取项目接收地址

  • 每个项目都有单独的数据接收地址
  • 请使用管理员账号获取响应项目的数据接收地址

2.2.2. 初始化 iOS SDK

2.2.2.1. Objective-C 初始化方式

如果您在创建 Flutter 项目时,iOS 端选择的语言是 Objective-C,可以这样初始化

//引入神策分析 SDK
#import <SensorsAnalyticsSDK/SensorsAnalyticsSDK.h>
 
  // 初始化配置
  SAConfigOptions *options = [[SAConfigOptions alloc] initWithServerURL:<#数据接收地址#> launchOptions:launchOptions];
 
  // 开启全埋点,可根据需求进行组合
  options.autoTrackEventType = SensorsAnalyticsEventTypeAppStart |
                 SensorsAnalyticsEventTypeAppEnd |
                 SensorsAnalyticsEventTypeAppClick |
                 SensorsAnalyticsEventTypeAppViewScreen;
#ifdef DEBUG
  // SDK 开启 Log
  options.enableLog = YES;
#endif
 
  /**
   * 其他配置
   */

  // 初始化 SDK
  [SensorsAnalyticsSDK startWithConfigOptions:options];
OBJECTIVE-C

2.2.2.2. Swift 初始化方式

若果您在创建 Flutter 项目时,iOS 端选择的语言是 Swift,可以这样初始化

import SensorsAnalyticsSDK

  // 初始化配置
  let configOptions = SAConfigOptions.init(serverURL: <#数据接收地址#>, launchOptions: launchOptions)
  // 开启全埋点,可根据需求进行组合
  configOptions.autoTrackEventType = [.eventTypeAppClick,.eventTypeAppEnd,.eventTypeAppStart,.eventTypeAppViewScreen]
  /**
   * 其他配置
   */

  // 初始化 SDK
  SensorsAnalyticsSDK.start(configOptions: configOptions)
SWIFT

2.3. 配置 Scheme

2.3.1. 获取项目 Scheme

  • 项目的 Scheme 需要管理员账户进行获取
  • App 工程可以同时配置多个项目的 Scheme

同获取数据接收地址的地方一致,在基本设置 →  数据接入 → 复制 scheme

2.3.2. App 中添加 Scheme

在 Flutter 项目的 ios 工程中选择 Target → Info → URL Types,点击加号(+),将上一步获取的 Scheme 配置到 URL Types 中:


2.3.3. 处理传入的 URL

在 AppDelete 的 -application:openURL:options: 方法中调用 -handleSchemeUrl: 对神策分析 Scheme 进行处理

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options{
  if ([[SensorsAnalyticsSDK sharedInstance] canHandleURL:url]) {
    return [[SensorsAnalyticsSDK sharedInstance] handleSchemeUrl:url];
  }
  return YES;
}
OBJECTIVE-C

3. Android 端

3.1. 集成神策分析 Android SDK

请参考 Android SDK 集成和初始化

4. 在 Flutter 中使用代码埋点

4.1. 在文件中引入神策 Flutter 插件

在具体的 dart 文件中引入神策插件,引入插件示例如下:

import 'package:sensors_analytics_flutter_plugin/sensors_analytics_flutter_plugin.dart';
CODE

4.2. 添加埋点事件

在合适的位置添加事件埋点,以按钮点击时触发事件为例:

其中对应的事件名为:AddToFav ;对应的事件自定义属性为:ProductID  和 UserLevel

SensorsAnalyticsFlutterPlugin.track("AddToFav", {"ProductID":123456,"UserLevel":"VIP"});
CODE

4.3. 用户登录

当用户注册成功或者登录成功时,需要调用 SDK 的 - login: 接口

SensorsAnalyticsFlutterPlugin.login("<#登录 ID#>");
CODE

为了准确记录登录用户的行为信息,建议在以下时机各调用一次 -login: 接口:

  • 用户在注册成功时
  • 用户登录成功时
  • 已登录用户每次启动 App 时

4.4. 记录激活事件

激活事件,建议在原生这边调用。

4.4.1. iOS 端记录激活事件

可以在初始化 SDK 后调用 - trackAppInstall 方法记录激活事件,多次调用此方法只会在第一次调用时触发激活事件:

#warning 需要 #import <AppTrackingTransparency/AppTrackingTransparency.h>
#warning iOS 14+ 使用 IDFA 需要在 info.plist 中添加 NSUserTrackingUsageDescription 字段,详情可参考 https://developer.apple.com/documentation/apptrackingtransparency
  if(@available(iOS 14, *)){
    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
      [[SensorsAnalyticsSDK sharedInstance] trackAppInstall];
    }];
  }else{
    [[SensorsAnalyticsSDK sharedInstance] trackAppInstall];
  
CODE

若用原记录的激活事件名不是 $AppInstall,需要使用虚拟事件将原激活事件和 $AppInstall 合并分析数据,具体咨询神策技术支持

4.4.2. Android 端记录激活事件

可以调用 trackAppInstall() 方法记录激活事件,多次调用此方法只会在第一次调用时触发激活事件:

if(Build.VERSION.SDK_INT >=Build.VERSION_CODES.M){
    if (ActivityCompat.checkSelfPermission(this, "android.permission.READ_PHONE_STATE") != PackageManager.PERMISSION_GRANTED) {
        // 6.0 以上,无权限时,先申请 READ_PHONE_STATE 权限。
        ActivityCompat.requestPermissions(this, new String[]{"android.permission.READ_PHONE_STATE"}, 100);
    } else {
        // 6.0 以上,有权限时,直接触发激活事件。
        trackAppInstall();
    }
} else {
    // 6.0 以下,无须申请权限,直接触发激活事件。
    trackAppInstall();
}
JAVA

在权限回调的 onRequestPermissionsResult() 方法中,申请权限结果回调无论申请权限成功失败,都要调用 trackAppInstall():

@Override
public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    if (requestCode == 100) {
        // 申请权限结果回调时(无论申请权限成功失败),都需要触发激活事件。
        trackAppInstall();
    }
}


/**
 * 记录激活事件
 */
private void trackAppInstall() {
    try {
        JSONObject properties = new JSONObject();
		//这里的 DownloadChannel 负责记录下载商店的渠道,值应传入具体应用商店包的标记。如果没有为不同商店打多渠道包,则可以忽略该属性的代码示例。
        properties.put("DownloadChannel", "XXX");
        // 触发激活事件
        SensorsDataAPI.sharedInstance().trackAppInstall(properties);
    } catch (Exception e) {
        e.printStackTrace();
    }
}
JAVA

若用原记录的激活事件名不是 $AppInstall,需要使用虚拟事件将原激活事件和 $AppInstall 合并分析数据,具体咨询神策技术支持

4.5. 设置事件公共属性

对于所有事件都需要添加的属性,初始化 SDK 后,可以使用-registerSuperProperties:方法将属性注册为公共属性:

SensorsAnalyticsFlutterPlugin.registerSuperProperties({"AppName":"FlutterDemo"});
CODE

公共属性会保存在 App 本地缓存中,可以通过 - unregisterSuperProperties: 删除一个指定公共属性;或使用 - clearSuperProperties: 删除所有已经设置的事件公共属性。

SensorsAnalyticsFlutterPlugin.unregisterSuperProperty("AppName");
SensorsAnalyticsFlutterPlugin.clearSuperProperties();
CODE

4.6. 设置用户属性

例如设置用户的 Age 属性:

SensorsAnalyticsFlutterPlugin.profileSet({"Age":"18"});
CODE