Flutter广告效果追踪插件tenjin_plugin的使用

Flutter广告效果追踪插件tenjin_plugin的使用

简介

Tenjin Flutter Plugin 允许用户在他们的 iOS/Android 应用中跟踪事件和安装。欲了解有关 Tenjin 和我们的产品提供的更多信息，请访问 Tenjin 官网。

插件集成

1. 添加依赖

在你的项目 pubspec.yaml 文件中添加依赖：

dependencies:
  tenjin_plugin: '^1.0.0'

2. 安装插件

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

$ flutter pub get

Android ProGuard 设置

在 proguard-rules.pro 文件中添加以下规则：

-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected Object[][] getContents();
}
-keepattributes *Annotation*

iOS 注意事项

对于 AppTrackingTransparency，确保更新你的项目 .plist 文件，并添加 NSUserTrackingUsageDescription 及其相应的提示信息。此库仅适用于 iOS 14.0+。更多信息请参阅 iOS 文档。

Android 注意事项

你需要在 gradle 依赖中添加 Google 的 Install Referrer Library。如果你还没有安装 Google Play Services，也需要添加：

dependencies {
  classpath("com.android.installreferrer:installreferrer:1.1.2")
  classpath("com.google.android.gms:play-services-analytics:17.0.0")
}

同时确保在 AndroidManifest.xml 中添加以下权限：

<manifest>
  ...
  <uses-permission android:name="android.permission.INTERNET"/>
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  ...
</manifest>

使用方法

初始化

获取你的 API_KEY，可以从 Tenjin 组织标签页 获取。你可以通过以下方式初始化 Tenjin：

TenjinSDK.instance.init(apiKey: '<API-KEY>');

你可以通过 Live Test Device Data Tool 验证是否成功连接。你可以在支持部分找到测试设备。转到 SDK Live 页面，并发送一个测试事件。你应该会看到实时事件传入：

GDPR 合规性

作为 GDPR 合规的一部分，你可以通过 Tenjin 的 SDK 来选择加入或退出设备/用户的操作，或者选择特定的设备相关参数来加入或退出。调用 OptOut() 将不会向 Tenjin 发送任何 API 请求，我们将不会处理任何事件。

TenjinSDK.instance.init(apiKey: '<API-KEY>');

bool userOptIn = checkOptInValue();

if (userOptIn) {
    TenjinSDK.instance.optIn();
} else {
    TenjinSDK.instance.optOut();
}

TenjinSDK.instance.connect();

要选择加入或退出特定的设备相关参数，可以使用 OptInParams() 或 OptOutParams() 方法。OptInParams() 只会发送指定的设备相关参数。OptOutParams() 会发送所有设备相关参数，除了那些被指定的参数。

TenjinSDK.instance.init(apiKey: '<API-KEY>');

List<String> optInParams = ["ip_address", "advertising_id", "developer_device_id", "limit_ad_tracking", "referrer", "iad"];
TenjinSDK.instance.optInParams(optInParams);

TenjinSDK.instance.connect();

设置 Google DMA 参数

如果你已经集成了 CMP（Consent Management Platform），Tenjin SDK 会自动收集 Google DMA 参数。你无需在 Tenjin SDK 中实现任何内容。

如果你想要覆盖你的 CMP，或者想要构建自己的同意机制，可以使用以下方法：

TenjinSDK.instance.setGoogleDMAParameters(adPersonalization, adUserData);

要显式管理 Google DMA 参数的收集，你可以在任何时候选择加入或退出。默认情况下为选择加入，你可以轻松调整偏好设置以确保完全控制你的数据隐私设置：

TenjinSDK.instance.optOutGoogleDMA();
TenjinSDK.instance.optInGoogleDMA();

设备相关参数

购买事件

为了理解用户收入和购买行为，开发者可以通过 Tenjin 发送 transaction 事件。有两种方式可以发送 transaction 事件给 Tenjin。

验证收据

Tenjin 可以验证 transaction 收据。示例如下：

TenjinSDK.instance.transactionWithReceipt(
  productId: 'productId',
  currencyCode: 'USD',
  quantity: 1,
  unitPrice: 3.80,
  iosReceipt: 'iosReceipt',
  iosTransactionId: 'transactionId',
  androidDataSignature: 'androidDataSignature',
  androidPurchaseData: 'androidPurchaseData',
);

TenjinSDK.instance.transaction(
  productId: 'productId',
  currencyCode: 'USD',
  quantity: 1,
  unitPrice: 3.80,
);

你可以通过 Live Test Device Data Tool 验证 IAP 验证是否工作。你应该会看到实时事件传入：

自定义事件

注意：不要在初始化之前发送自定义事件。初始化事件必须先于任何自定义事件发送。

重要：限制自定义事件名称少于 80 个字符。不要超过 500 个唯一的自定义事件名称。

你可以使用 Tenjin SDK 传递自定义事件：eventWithName(String name)。

自定义交互可以与你使用的每个收购源的成本联系起来。示例如下：

// 集成一个带有特定名称的自定义事件 - 例如，屏幕上的右滑
TenjinSDK.instance.eventWithName("swipe_right");

传递带整数值的自定义事件：

// 传递一个带有整数值的自定义事件
TenjinSDK.instance.eventWithNameAndValue("item", 100);

使用上述示例，Tenjin 仪表板将汇总并平均所有名为 item 的事件的值。

请注意，如果传递的值不是整数，则该事件将不起作用。

深度链接

Tenjin 支持通过 Tenjin 的活动跟踪 URL 导航用户到应用内的特定部分。你可以利用 getDeeplink 方法和回调来访问通过数据对象返回的延迟深度链接。示例如下：

TenjinSDK.instance.setRewardCallback = (bool clickedTenjinLink,
        bool isFirstSession, Map<String, String> data) {
      if (isFirstSession) {
        if (clickedTenjinLink) {
          if (data.containsKey(TenjinSDK.DEEPLINK_URL)) {
            // 使用延迟深度链接 URL 将用户导航到应用的特定部分
          }
        }
      }
    };

以下是延迟深度链接回调中可能返回的参数：

你还可以使用 v1.7.1+ SDK 通过检查 isFirstSession 参数来处理安装后的逻辑。例如，如果你有一个付费应用，你可以这样注册你的付费应用安装：

TenjinSDK.instance.init(apiKey: '<API-KEY>');
TenjinSDK.instance.setRewardCallback = (bool clickedTenjinLink,
        bool isFirstSession, Map<String, String> data) {
      if (isFirstSession) {
          // 发送付费应用价格和收入到 Tenjin
      }
    };

A/B 测试的应用子版本参数（需要 DataVault）

如果你正在进行 A/B 测试并希望报告差异，我们可以使用 appendAppSubversion 方法将一个数字附加到你的应用版本。例如，如果你的应用版本是 1.0.1，并设置 appendAppSubversion: 8888，它将报告为 1.0.1.8888。

此数据将出现在 DataVault 中，你可以在其中使用应用子版本值生成报告。

TenjinSDK.instance.init(apiKey: '<API-KEY>');
TenjinSDK.instance.appendAppSubversion(8888);
TenjinSDK.instance.connect();

其他可用方法

客户用户 ID

TenjinSDK.setCustomerUserId(userId)

TenjinSDK.getCustomerUserId()

获取分析安装 ID

String? analyticsId = await TenjinSDK.instance.getAnalyticsInstallationId();

发送 AdMob 印象（ILRD）

TenjinSDK.eventAdImpressionAdMob(json)

发送 AppLovin 印象（ILRD）

TenjinSDK.eventAdImpressionAppLovin(json)

发送 HyperBid 印象（ILRD）

TenjinSDK.eventAdImpressionHyperBid(json)

发送 IronSource 印象（ILRD）

TenjinSDK.eventAdImpressionIronSource(json)

发送 TopOn 印象（ILRD）

TenjinSDK.eventAdImpressionTopOn(json)

发送 TradPlus 印象（ILRD）

TenjinSDK.eventAdImpressionTradPlus(json)
TenjinSDK.eventAdImpressionTradPlusAdInfo(adInfo)

支持

如果你在插件集成或使用过程中遇到任何问题，请联系我们：support@tenjin.com

示例代码

import 'dart:io';

import 'package:flutter/material.dart';
import 'package:tenjin_plugin/tenjin_sdk.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  [@override](/user/override)
  void initState() {
    TenjinSDK.instance.init(apiKey: '<API-KEY>');
    TenjinSDK.instance.optIn();
    TenjinSDK.instance.registerAppForAdNetworkAttribution();
    super.initState();
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Tenjin SDK')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.spaceEvenly,
            children: [
              TextButton(
                onPressed: () => TenjinSDK.instance.connect(),
                child: Text('connect'),
              ),
              TextButton(
                onPressed: () => TenjinSDK.instance.eventWithName('swipe_right'),
                child: Text('eventWithName'),
              ),
              TextButton(
                onPressed: () => TenjinSDK.instance.eventWithNameAndValue('item', 100),
                child: Text('eventWithNameAndValue'),
              ),
              if (Platform.isIOS)
                TextButton(
                  onPressed: () {
                    TenjinSDK.instance.requestTrackingAuthorization();
                  },
                  child: Text('Request Tracking Authorization'),
                ),
              TextButton(
                onPressed: () {
                  TenjinSDK.instance.transactionWithReceipt(
                    productId: 'productId',
                    currencyCode: 'USD',
                    quantity: 1,
                    unitPrice: 3.80,
                    iosReceipt: 'iosReceipt',
                    iosTransactionId: 'transactionId',
                    androidDataSignature: 'androidDataSignature',
                    androidPurchaseData: 'androidPurchaseData',
                  );
                },
                child: Text('Transaction with Receipt'),
              ),
              TextButton(
                onPressed: () {
                  TenjinSDK.instance.transaction('productId', 'USD', 1, 3.80);
                },
                child: Text('Transaction'),
              ),
              TextButton(
                onPressed: () {
                  TenjinSDK.instance.updatePostbackConversionValue(3);
                },
                child: Text('Update SKAN'),
              ),
              TextButton(
                onPressed: () {
                  TenjinSDK.instance.setCustomerUserId('test_user_id');
                },
                child: Text('Set customer userId'),
              ),
              TextButton(
                onPressed: () async {
                  try {
                    String? userId = await TenjinSDK.instance.getCustomerUserId();
                    if (userId != null) {
                      print(userId);
                    } else {
                      print('Failed to get customer user id');
                    }
                  } catch (e) {
                    print('Error: $e');
                  }
                },
                child: Text('Get user id'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}