Flutter跟踪分析插件trackier_sdk_flutter的使用

快速开始指南

我们已经创建了一个示例应用来展示如何集成flutter sdk。

请查看示例目录，了解如何将Trackier SDK集成到你的应用中。

添加Flutter SDK到你的应用

在你的应用中集成Flutter SDK非常简单。只需要遵循以下步骤：

方法一：通过添加依赖到pubspec.yaml文件

dependencies:
  trackier_sdk_flutter: ^1.6.61

方法二：通过CLI命令

在终端或命令提示符中运行以下命令：

$ flutter pub add trackier_sdk_flutter

该命令会直接将Trackier SDK添加到你的pubspec.yaml文件中。之后运行以下命令更新包：

$ flutter packages get

更新Pod依赖

对于iOS应用，确保进入ios文件夹并安装Cocoapods依赖：

$ cd ios && pod install

添加Android安装引用

在你的应用的build.gradle文件中添加Android安装引用作为依赖。你可以在这里找到最新版本：

dependencies {
  // 确保使用最新的SDK版本:
  implementation 'com.android.installreferrer:installreferrer:2.2'
}

添加必需权限

Trackier SDK需要在AndroidManifest.xml中添加以下权限：

<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" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />

获取Google广告ID

Trackier SDK需要从应用中获取广告ID。

为此，你需要在build.gradle和AndroidManifest.xml中添加一些代码以读取广告ID：

在android/app/build.gradle中添加依赖

dependencies {
  // 这可以在SDK依赖添加的地方添加
  implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}

更新AndroidManifest.xml文件

如果你的应用目标设备的Android版本为12及以上，则需要添加以下权限：

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

在AndroidManifest.xml的application标签内添加元数据

<meta-data
  android:name="com.google.android.gms.version"
  android:value="@integer/google_play_services_version" />

集成和初始化Trackier SDK

获取开发密钥

要初始化Trackier SDK，首先需要从Trackier MMP面板生成SDK密钥。

以下是获取开发密钥的步骤：

• 登录你的Trackier面板。
• 选择你的应用，并点击操作按钮登录。
• 在仪表板中，点击左侧菜单中的SDK Integration选项。
• 在SDK Integration下，你将获得SDK密钥。

遵循所有步骤后，你的SDK密钥看起来像下面的截图：

在Flutter应用中集成Trackier SDK

应在main.dart类的initState()方法中初始化SDK。

以下是初始化SDK的示例代码：

class _MyHomePageState extends State<MyHomePage> {

  @override
  void initState() {
    super.initState();
    initilalizeSdk();
  }

  Future<void> initilalizeSdk() async {

    String key = "xxxx-xx-4505-bc8b-xx"; // 请传递你的开发密钥

    /* 初始化SDK时，需要传递两个参数给TrackierSDKConfig。
     * 第一个参数需要传递Trackier SDK API密钥，
     * 第二个参数需要传递环境，可以是"development"、"production"或"testing"。*/

    TrackerSDKConfig trackerSDKConfig = TrackerSDKConfig(key, "production");
    Trackierfluttersdk.initializeSDK(trackerSDKConfig);

  }
}

你也可以检查以下示例代码的截图：

重要：初始化SDK时必须使用正确的开发密钥。使用错误的开发密钥会影响从SDK发送的所有流量，并导致归因和报告问题。

事件跟踪

获取事件ID

Trackier事件跟踪提供了用户与您的应用互动的见解。只需按照简单的事件集成过程即可获取这些见解数据。

Trackier在Trackier面板上提供了内置事件和自定义事件。

内置事件

预定义事件是一些常量事件，已经在仪表板上创建。

您可以直接使用这些事件进行跟踪。只需在项目中实现这些事件。

调用内置事件的示例代码

/*
 * 事件跟踪
 * ------------------------------
 * 下面的代码是一个示例，用于向Trackier SDK传递一个事件。
 * 此事件仅需要一个参数，即事件ID。
 * 下面是内置事件函数调用的示例
 * 参数 "TrackierEvent.LOGIN" 传递给Trackier事件类是事件ID
 */
void _eventsTracking() {
  TrackierEvent trackierEvent = TrackierEvent(TrackierEvent.LOGIN);

  /* 以下是可以添加额外数据的功能，
     您可以添加诸如用户的登录详细信息或其他任何需要的数据。
     我们有10个参数可以添加数据，以下是其中5个 */
  trackierEvent.param1 = "param1";
  trackierEvent.param2 = "param2";
  trackierEvent.param3 = "param3";
  trackierEvent.param4 = "param4";
  trackierEvent.param5 = "param5";

  trackierEvent.setEventValue("ev1", "eventValue1");
  trackierEvent.setEventValue("ev2", 1);
  Trackierfluttersdk.trackEvent(trackierEvent);
}

注意：Trackier事件类中的参数是事件ID。

您可以将内置参数与事件一起集成。内置参数列表如下：

orderId, revenue, currency, param1, param2, param3, param4, param5, param6, param7, param8, param9, param10。

下面是示例代码的截图：

自定义事件

自定义事件是根据用户所需业务逻辑创建的。

您可以在Trackier仪表板上创建事件，并在项目中集成这些事件。

调用自定义事件的示例代码

/*
 * 事件跟踪
 * ------------------------------
 * 下面的代码是一个示例，用于向Trackier SDK传递一个事件。
 * 此事件仅需要一个参数，即事件ID。
 * 下面是自定义事件函数调用的示例，事件名为"AppOpen"
 * 参数 "sEMWSCTXeu" 传递给Trackier事件类是事件ID
 */
void _eventsTracking() {
  TrackierEvent trackierEvent = TrackierEvent("sEMWSCTXeu");

  /* 以下是可以添加额外数据的功能，
     您可以添加诸如用户的登录详细信息或其他任何需要的数据。
     我们有10个参数可以添加数据，以下是其中5个 */
  trackierEvent.param1 = "param1";
  trackierEvent.param2 = "param2";
  trackierEvent.param3 = "param3";
  trackierEvent.param4 = "param4";
  trackierEvent.param5 = "param5";

  trackierEvent.setEventValue("ev1", "eventValue1");
  trackierEvent.setEventValue("ev2", 1);
  Trackierfluttersdk.trackEvent(trackierEvent);
}

你也可以检查上面代码的截图：

收入事件跟踪

Trackier允许用户通过收入事件传递应用程序生成的收入数据。这主要用于记录应用程序产生的收入，并且还可以传递货币。

void _revenueEventsTracking() {
  // 以下是一个收入事件函数调用的示例
  // 参数 "TrackierEvent.LOGIN" 传递给事件类是事件ID
  TrackierEvent trackierEvent = TrackierEvent(TrackierEvent.LOGIN);

  // 传递收入事件的示例如下
  trackierEvent.revenue = 10.0; // 传递生成的收入
  trackierEvent.currency = "INR"; // 传递货币
  trackierEvent.orderId = "orderID";
  trackierEvent.param1 = "param1";
  trackierEvent.param2 = "param2";
  trackierEvent.setEventValue("ev1", "eventValue1");
  trackierEvent.setEventValue("ev2", 1);
  Trackierfluttersdk.trackEvent(trackierEvent);
}

在事件中传递自定义参数

void customParamTracking() {
  // 以下是一个收入事件函数调用的示例
  // 参数 "TrackierEvent.LOGIN" 传递给事件类是事件ID
  TrackierEvent trackierEvent = TrackierEvent(TrackierEvent.LOGIN);

  // 在事件中传递自定义参数的示例如下
  var eventCustomParams = Map<String, Object>();
  eventCustomParams = {"name": "abcd"};
  eventCustomParams = {"age": "28"};
  trackierEvent.evMap = eventCustomParams;
  Trackierfluttersdk.trackEvent(trackierEvent);
}  

• 首先创建一个映射。
• 将映射的引用传递给trackierEvent.evMap参数。
• 将事件引用传递给TrackierSDK的trackEvent方法。

向SDK传递用户数据

Trackier允许传递用户ID、电子邮件等附加数据，以便将其与Trackier数据和日志相关联。

只需将用户ID、电子邮件ID和其他附加数据传递给Trackier SDK函数，如下面所示：

void userDetails() {
  /* 传递用户ID和电子邮件ID数据 */
  Trackierfluttersdk.setUserId("XXXXXXXX"); // 传递用户ID值
  Trackierfluttersdk.setUserEmail("abc@gmail.com"); // 传递用户电子邮件ID
}

传递附加数据

Trackier允许传递用户姓名、手机号码、用户年龄、用户性别等附加用户详细信息。您需要首先创建一个哈希映射，然后将其传递给setUserAdditionalDetail函数。示例如下：

void userDetails() {
  /* 传递用户ID和电子邮件ID数据 */
  Trackierfluttersdk.setUserId("XXXXXXXX"); // 传递用户ID值
  Trackierfluttersdk.setUserEmail("abc@gmail.com"); // 传递用户电子邮件ID

  /* 传递附加数据 */
  var userDetails = Map<String, Object>();
  userDetails = {"name": "abcd"}; // 您可以传递用户名数据。
  userDetails = {"mobile_number": "872xxxxx87"}; // 您可以传递用户手机号码
  Trackierfluttersdk.setUserAdditonalDetail(userDetails);
}

跟踪Android卸载

开始之前

• 安装并添加初始化代码到你的应用中，如果尚未完成。
• 将你的应用添加到Firebase项目中。

添加分析SDK到你的应用

• 从Flutter项目的根目录运行以下命令以安装插件：

flutter pub add firebase_analytics

• 一旦完成，重新构建你的Flutter应用：

flutter run

• 一旦安装完成，你可以在Dart代码中导入firebase_analytics插件：

import 'package:firebase_analytics/firebase_analytics.dart';

• 创建一个新的Firebase Analytics实例，通过调用FirebaseAnalytics的instance获取器：

FirebaseAnalytics analytics = FirebaseAnalytics.instance;

• 使用上面获得的analytics实例设置以下用户属性：

var trackierId = await Trackierfluttersdk.getTrackierId();
analytics.setUserProperty(name: "ct_objectId", value: trackierId);

• 上述代码添加了通用标识符。
• 设置app_remove事件为Firebase中的转化事件。
• 使用Firebase云功能将卸载信息发送到Trackier MMP。
• 你可以在这里找到支持文章：支持文章。

SDK签名

以下是获取secretId和secretKey的步骤：

• 登录你的Trackier面板并选择你的应用。
• 在仪表板中，点击左侧面板上的SDK Integration选项。
• 在SDK Integration下，点击Advanced选项卡。
• 在Advanced选项卡下，你会得到secretId和secretKey。

请参见下面的截图：

检查下面的示例代码，将secretId和secretKey传递给SDK：

class _MyHomePageState extends State<MyHomePage> {

  @override
  void initState() {
    super.initState();
    initilalizeSdk();
  }

  Future<void> initilalizeSdk() async {

    String key = "xxxx-xx-4505-bc8b-xx"; // 请传递你的开发密钥

    /* 初始化SDK时，需要传递两个参数给TrackierSDKConfig。
     * 第一个参数需要传递Trackier SDK API密钥
     * 第二个参数需要传递环境，可以是"development"、"production"或"testing"。 */

    TrackerSDKConfig trackerSDKConfig = TrackerSDKConfig(key, "production");
    trackerSDKConfig.setAppSecret("xxx", "xxx-xx");
    Trackierfluttersdk.initializeSDK(trackerSDKConfig);

  }
}

深度链接

深度链接是一种技术，用户可以通过点击深度链接URL直接跳转到应用的特定页面。

深度链接有两种类型：

• 普通深度链接：当用户已在其设备上安装你的应用时，深度链接会将其重定向到链接中指定的屏幕。
• 延迟深度链接：当用户未在其设备上安装你的应用时，深度链接会首先将用户重定向到设备的应用商店以安装你的应用。当用户第一次打开应用时，SDK将读取深度链接内容。

请参阅下面的深度链接场景图：

普通深度链接

如果用户已经在他们的设备上安装了你的应用，当他们与包含深度链接的跟踪器交互时，应用将会打开。你可以解析深度链接信息以供进一步使用。为此，你需要选择一个独特的方案名称。

你可以设置一个特定的活动，当用户与深度链接交互时启动。为此：

• 在AndroidManifest.xml文件中为活动分配唯一的方案名称。
• 向活动定义添加intent-filter部分。
• 分配android:scheme属性值为你的首选方案名称。

例如，你可以这样设置一个名为FirstActivity的活动：

<activity
  android:name=".Activity.FirstProduct"
  android:exported="true">
  <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="trackier.u9ilnk.me"
      android:pathPrefix="/product"
      android:scheme="https" />
  </intent-filter>
</activity>

https://trackier.u9ilnk.me/product?dlv=FirstProduct&quantity=10&pid=sms

延迟深度链接

当用户没有在他们的设备上安装你的应用时，延迟深度链接会发生。当用户点击Trackier URL时，URL将把他们重定向到Play Store下载和安装你的应用。当用户第一次打开应用时，SDK将读取深度链接内容。

Trackier SDK默认会打开延迟深度链接。只需要在初始化Trackier SDK后，在应用类中添加一些代码：

class _MyAppState extends State<MyApp> {
  String _platformVersion = 'Unknown';

  @override
  void initState() {
    super.initState();
    initPlatformState();
  }

  Future<void> initPlatformState() async {
    TrackerSDKConfig trackerSDKConfig = new TrackerSDKConfig(
      "0455721b-xxxx-xxxx-xxxx-596d818d910a",
      "development"
    );

    // 获取深度链接数据的方法
    trackerSDKConfig.deferredDeeplinkCallback = (uri) {
      print('The value of deeplinkUrl is: $uri');
    };
    Trackierfluttersdk.initializeSDK(trackerSDKConfig);
  }
}

获取活动数据

为了获取活动数据，我们有一个函数可以返回活动数据。请参阅下面的示例代码。

_gettingCampaigData() {
  TrackierEvent trackierEvent = new TrackierEvent("1CFfUn3xEY");
  var ad = await Trackierfluttersdk.getAd();
  var getAdID = await Trackierfluttersdk.getAdID();
  var getCampaign = await Trackierfluttersdk.getCampaign();
  var getCampaignID = await Trackierfluttersdk.getCampaignID();
  var getAdSet = await Trackierfluttersdk.getAdSet();
  var getAdSetID = await Trackierfluttersdk.getAdSetID();
  var getP1 = await Trackierfluttersdk.getP1();
  var getP2 = await Trackierfluttersdk.getP2();
  var getP3 = await Trackierfluttersdk.getP3();
  var getP4 = await Trackierfluttersdk.getP4();
  var getP5 = await Trackierfluttersdk.getP5();
  var getClickId = await Trackierfluttersdk.getClickId();
  var getDlv = await Trackierfluttersdk.getDlv();
  var getPid = await Trackierfluttersdk.getPid();
  var getIsRetargeting = await Trackierfluttersdk.getIsRetargeting();
  Trackierfluttersdk.trackerEvent(trackierEvent);
}

ProGuard设置

如果您的应用使用ProGuard，请在ProGuard配置文件中添加以下行：

-keep class com.trackier.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }