中文 EN RU 中文

Android

连接Android版MyTracker SDK。您可以使用现成的Java和Kotlin演示应用程序为例。

最低要求

  • 支持的最低Android版本 — 4.0版(API Level 14)。

  • 项目一定要有程序库Google Play Services (com.google.android.gms:play-services-ads-identifier模块)和Google Play Install Referrer (com.android.installreferrer:installreferrer模块).

  • 对于Huawei App Store的应用程序项目一定要有程序库 Huawei Media Services (com.huawei.hms:hms-ads-identifier, com.huawei.hms:ads-installreferrer模块),以便MyTracker获取Huawei OAID,Install Referrer。

集成

使用Gradle连接

将依赖项添加到项目的build.gradle文件的dependencies部分:

dependencies {
    //... 其他依赖项
    implementation 'com.my.tracker:mytracker-sdk:2.1.+'
}

手动结合

  • 下载 . MyTracker.aar最新版本.

  • 将所下载的aar文件以依赖项的形式添加到项目中。

  • 将以下依赖项添加到您的应用build.gradle文件中:

    dependencies {
    ...
    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.0'
    implementation 'com.google.android.gms:play-services-appset:16.0.1'
    }
  • (可选或者在使用jar情况的下)如果您使用的是Proguard,请添加例外:

    -keep class com.my.tracker.** { *; }
    -dontwarn com.my.tracker.**
    -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 class com.android.installreferrer.** { *; }
    -keep class com.android.vending.billing.** { *; }
    -keep class com.android.billingclient.api.** { *; }

所需权限

(可选或者在使用jar的情况下)将所需权限添加到您应用程序的AndroidManifest.xml文件的manifest部分:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    ...
     >
    ...
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
    ...
</manifest>

初始化

为了确保MyTracker SDK正确工作,您需要在您的Application类应用程序中使用onCreate方法对跟踪器进行调整和初始化。为了进行跟踪器初始化,您需要输入SDK_KEY,但在此之前还需要进行必要的调整(配置、用户跟踪、深层链接等调整)。

SDK_KEY is generated automatically after you added your application to MyTracker. To get the key, go to the Application list page, select the required application, and copy the key from the Overview tab.

public class YourApplicationClass extends Application
{
    @Override
    public void onCreate()
    {
        super.onCreate();

        // 如有需要,对跟踪器配置进行调整
        MyTrackerParams trackerParams = MyTracker.getTrackerParams();
        MyTrackerConfig trackerConfig = MyTracker.getTrackerConfig();
        // …
        // 调整跟踪器的参数
        // …
        // 进行跟踪器初始化
        MyTracker.initTracker(SDK_KEY, this);
    }
}
class YourApplicationClass : Application()
{
    override fun onCreate()
    {
        super.onCreate()

        // 如有需要,对跟踪器配置进行调整
        val trackerParams = MyTracker.getTrackerParams()
        val trackerConfig = MyTracker.getTrackerConfig()
        // ...
        // 调整跟踪器的参数
        // ...

        // 进行跟踪器初始化
        MyTracker.initTracker(SDK_KEY, this)
    }
}

如果无法在Application类中对跟踪器进行初始化,则可以在应用程序的第一个启动活动中对其进行初始化。在这种情况下,跟踪器初始化后,需要调用trackLaunchManually方法。

public class YourActivity extends Activity
{
    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);


        // 如有需要,对跟踪器配置进行调整
        MyTrackerParams trackerParams = MyTracker.getTrackerParams();
        MyTrackerConfig trackerConfig = MyTracker.getTrackerConfig();
        // ...
        // 调整跟踪器的参数
        // ...
        // 进行跟踪器初始化
        MyTracker.initTracker(SDK_KEY, getApplication());
        MyTracker.trackLaunchManually(this);
    }
}
class YourActivity : Activity()
{
    override fun onCreate(savedInstanceState: Bundle?)
    {
        super.onCreate(savedInstanceState)

        // 如有需要,对跟踪器配置进行调整
        val trackerParams = MyTracker.getTrackerParams()
        val trackerConfig = MyTracker.getTrackerConfig()
        // ...
        // 调整跟踪器的参数
        // ...

        // 进行跟踪器初始化
        MyTracker.initTracker(SDK_KEY, getApplication())
        MyTracker.trackLaunchManually(this)
    }
}

API

跟踪器的配置

跟踪器的配置可以通过MyTrackerConfig类的实例,以及 MyTracker.getTrackerConfig()方法进行调整。跟踪器的参数可以通过MyTrackerParams类的实例,以及MyTracker.getTrackerParams()方法进行设置。可以设定以下参数(选项):

TrackingLaunchEnabled: 应用程序启动跟踪。默认值 true

@NonNull MyTrackerConfig setTrackingLaunchEnabled(boolean trackingLaunchEnabled)
fun setTrackingLaunchEnabled(trackingLaunchEnabled: Boolean): MyTrackerConfig

LaunchTimeout: 当应用程序最小化时,在以秒为单位计算的时间间隔内,应用的新启动不会被计算,且会话不被中断。默认值:30秒。调整范围:30—7200秒。

@NonNull MyTrackerConfig setLaunchTimeout(int seconds)
fun setLaunchTimeout(seconds: Int): MyTrackerConfig

BufferingPeriod: 在以秒为单位计算的时间间隔内,事件在发送到服务器之前将积累在相关设备上。默认值:900秒。调整范围:1—86400秒(1天)。

@NonNull MyTrackerConfig setBufferingPeriod(int seconds)
fun setBufferingPeriod(seconds: Int): MyTrackerConfig

ForcingPeriod: 应用安装或更新后在以秒为单位计算的时间间隔内,事件会立刻被发送到服务器,无需进行本地缓冲。默认值:0秒(包含立刻发送)。调整范围:0—432000秒。(5天)。

@NonNull MyTrackerConfig setForcingPeriod(int seconds)
fun setForcingPeriod(seconds: Int): MyTrackerConfig

AutotrackingPurchaseEnabled: 自动跟踪应用内的购买情况。默认值 true

@NonNull MyTrackerConfig setAutotrackingPurchaseEnabled(boolean autotrackingPurchaseEnabled)
fun setAutotrackingPurchaseEnabled(autotrackingPurchaseEnabled: Boolean): MyTrackerConfig

TrackingLocationEnabled:跟踪用户的位置信息。默认值 false

If your application requests location access, you can enable this parameter to improve the accuracy of statistics related to the user geography. In some cases, location tracking also improves attribution and predictive models (Fraud Scanner, Personalize, LTV Predictions, etc.).

The parameter is disabled by default since SDK version 3.0.9

@NonNull MyTrackerConfig setTrackingLocationEnabled(boolean trackingLocationEnabled)
fun setTrackingLocationEnabled(trackingLocationEnabled: Boolean): MyTrackerConfig

TrackingPreinstallEnabled: pre-installs tracking. True by default. MyTracker will catch pre-installs if you share an application and a special JSON-file with the device manufacturer.

@NonNull MyTrackerConfig setTrackingPreinstallEnabled(boolean trackingPreinstallEnabled)
fun setTrackingPreinstallEnabled(trackingPreinstallEnabled: Boolean): MyTrackerConfig

Region: 统计收集服务器所在的区域。例如,由于法律要求,需要更换区域。可用的值:

  • Region.RU — 俄罗斯联邦境内的服务器

  • Region.EU — 欧盟境内的服务器

@NonNull MyTrackerConfig setRegion(int region)
fun setRegion(region: Int): MyTrackerConfig

打开/关闭调试模式

通过MyTracker类静态方法可以打开/关闭调试模式。默认值:false

@AnyThread
void setDebugMode(boolean debugMode)
@AnyThread
            fun setDebugMode(debugMode: Boolean)

用户跟踪

请设置customUserId参数,以便既跟踪设备,又跟踪用户统计。这个参数是您的项目在用户注册时分配给用户的唯一ID。即使用户使用其他设备进行登录, ID仍保持不变。设置该参数以后,无论用户使用多少设备,您都可以评估应用软件受众的规模以及活动详情。如果用户决定更换设备,您也不会丢失用户数据累积的历史记录。

重要的是一定要在事件跟踪之前设置参数,以保证每次跟踪事件时,都会发送有关UserID。

public void setUserInfo()
{
    MyTrackerParams trackerParams = MyTracker.getTrackerParams();

    // 设置用户的ID
     trackerParams.setCustomUserId("user_id");

}
fun setUserInfo()
{
    val trackerParams = MyTracker.getTrackerParams()

    // 设置用户的ID
    trackerParams.setCustomUserId("user_id")

}

如果在设置customUserId之前,在应用程序中形成了已注册用户的数据库,那么MyTracker将无法获取有关该用户注册时间的数据,并且无法进行Lifetime指标的准确计算。对于此类用户,生命周期统计将根据customUserId首次目标跟踪的日期进行计算。

若要禁用用户跟踪,请传递customUserId参数中的空值。

事件跟踪

可以通过静态MyTracker方法发送事件。在方法调用之前,设置customUserId参数以将用户 ID 与每个跟踪事件一起传输。

您可以使用以下方法跟踪各种事件:

注册事件。 用户在应用程序中完成注册,并获取唯一ID后,您就要立刻调用该方法。在调用TrackRegistrationEvent前一定要设定customUserId参数,否则有关事件将在没有用户ID信息的情况下被传送,导致统计不准确。

userId is a required parameter since SDK version 2.0.8

@AnyThread
void trackRegistrationEvent(@NonNull String userId)
@AnyThread
fun trackRegistrationEvent(userId: String)

授权事件。 用户在应用程序中完成登录并获取唯一ID后,您就要立刻调用该方法。在调用TrackLoginEvent前一定要设定customUserId参数,否则有关事件将在没有用户ID信息的情况下被传送,导致统计不准确。

userId is a required parameter since SDK version 2.0.8

@AnyThread
void trackLoginEvent(@NonNull String userId)
@AnyThread
fun trackLoginEvent(userId: String)

邀请发送事件。 eventParams附加参数允许为事件设定任意键值参数。键和值的最大长度为255个字符。

@AnyThread
void trackInviteEvent()
@AnyThread
void trackInviteEvent(@Nullable Map<String, String> eventParams)
@AnyThread
fun trackInviteEvent()

@AnyThread
fun trackInviteEvent(eventParams: Map<String, String>?)

升级事件。 该事件发送时可以包括具体级别信息(level参数),也可以不包括。eventParams附加参数允许为事件设定任意键值参数。键和值的最大长度为255个字符。

@AnyThread
void trackLevelEvent()
@AnyThread
void trackLevelEvent(@Nullable Map<String, String> eventParams)
@AnyThread
void trackLevelEvent(int level, @Nullable Map<String, String> eventParams)
@AnyThread
fun trackEvent(name: String)

@AnyThread
fun trackEvent(name: String, eventParams: Map<String, String>?)

具有指定名称的任意事件。 eventParams附加参数允许为事件设定任意键值的参数。键和值的最大长度为255个字符。

@AnyThread
void trackEvent(@Nullable String name)
@AnyThread
void trackEvent(@Nullable String name, @Nullable Map<String, String> eventParams)
@AnyThread
fun trackEvent(name: String)

@AnyThread
fun trackEvent(name: String, eventParams: Map<String, String>?)

例子:

Map<String, String> eventCustomParams = new HashMap<>();
eventCustomParams.put("someParamKey1", "someParamValue1");
eventCustomParams.put("someParamKey2", "someParamValue2");
MyTracker.trackCustomEvent("eventName", eventCustomParams);
val eventCustomParams = HashMap<String, String>()
eventCustomParams["someParamKey1"] = "someParamValue1";
eventCustomParams["someParamKey2"] = "someParamValue2";
MyTracker.trackCustomEvent("eventName", eventCustomParams);

强制发送所有的事件并且重置发送计时器。

为了减少信道负载,且最大程度地减少对应用程序性能的影响,在把事件发送到服务器之前,SDK会把设备上的所有事件累积在缓冲区,并定期以压缩包的形式发送收集到的数据。默认情况下,每15分钟一次将数据发送到服务器。您可以通过bufferingPeriod参数在1秒到1天的范围内调整时间间隔。如果用户已关闭了该应用程序,数据将在下次启动时被发送。但是,某些事件对于尽早进入分析至关重要,尤其是在应用程序安装后的第一个会话种。用flush()方法可以达成这个目的。

@AnyThread
void flush()
@AnyThread
fun flush()

应用内购买跟踪

Play Billing Library

如果您使用的是 Play Billing Library,为实现自动购买跟踪,需要从BillingClient侦听器的 onPurchasesUpdated方法中调用相应的MyTracker方法。

private BillingClient client;
    ...
    client = BillingClient.newBuilder(context)
                     .setListener(new PurchasesUpdatedListener()
                     {
                        @Override
                        public void onPurchasesUpdated(int responseCode, @Nullable List<Purchase> purchases)
                        {
                            MyTracker.onPurchasesUpdated(responseCode, (List) purchases);


                            // 您的购买代码
                            // ...
                        }
                     })
                     .build();
    ...
private var client: BillingClient? = null
// ...
client = BillingClient.newBuilder(this)
                .setListener { billingResult, purchases ->
                    MyTracker.onPurchasesUpdated(billingResult.responseCode, purchases as List<Any>?)
                    // ...
                    // 您的购买代码
                    // ...
                }
                .build()
// ...

In-app Billing API

如果您使用自己应用内的In-App Billing API来实施自动购买跟踪,则需要从启动购买过程的 onActivityResult活动方法中调用相应的MyTracker方法。

public static final int PURCHASE_REQUEST_CODE = 1001;
...
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data)
{
   super.onActivityResult(requestCode, resultCode, data);
   if (requestCode == PURCHASE_REQUEST_CODE)
   {
        MyTracker.onActivityResult(resultCode, data);
        // 您的购买代码
        // ...
   }
}
...
// ...
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
{
    super.onActivityResult(requestCode, resultCode, data)
    if (PURCHASE_REQUEST_CODE == requestCode)
    {
        MyTracker.onActivityResult(resultCode, data)
        // ...
        // 您的购买代码
        // ...
    }
}
// ...
companion object
{
    const val PURCHASE_REQUEST_CODE = 1001
}

手动购买跟踪

如果您想手动跟踪购买,需要使用关参数autotrackingPurchaseEnabled = false关闭自动跟踪,并且使用以下方法:

@AnyThread
void trackPurchaseEvent(@NonNull JSONObject skuDetails,
       @NonNull JSONObject purchaseData,
       @NonNull String dataSignature)
@AnyThread
void trackPurchaseEvent(@NonNull JSONObject skuDetails,
       @NonNull JSONObject purchaseData,
       @NonNull String dataSignature,
       @Nullable Map<String, String> eventParams)
@AnyThread
fun trackPurchaseEvent(skuDetails: JSONObject,
                       purchaseData: JSONObject,
                       dataSignature: String)

@AnyThread
fun trackPurchaseEvent(skuDetails: JSONObject,
                       purchaseData: JSONObject,
                       dataSignature: String,
                       eventParams: Map<String, String>?)

启动自动跟踪的情况下,以上方法的调用会被忽略。强制参数(选项):

  • skuDetails根据文档,skuDetails是对google API 购买请求的响应。
  • purchaseData根据文档,在INAPP_PURCHASE_DATA字段中,purchaseData 是响应 getBuyIntent 请求JSON对象。
  • dataSignature — 是响应INAPP_DATA_SIGNATURE字段中的 getBuyIntent 请求的行。

getSkuDetails()getBuyIntent()的响应是以Bundle形式发过来的,其中的字段有String类型,在发送之前需要转换成 JSONObject。

eventParams附加参数允许为事件设定任意键值的参数。键和值的最大长度为255个字符。

public static final int PURCHASE_REQUEST_CODE = 1001;
...
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data)
{
   super.onActivityResult(requestCode, resultCode, data);
   if (requestCode == PURCHASE_REQUEST_CODE && resultCode == RESULT_OK)
   {
      try
      {
         final String purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA");
         final String dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE");

         final JSONObject purchaseDataJson = new JSONObject(purchaseData);

         // 自己获取skuDetails
         final JSONObject skuDetailsJson = obtainSkuDetailJson(purchaseData);

         MyTracker.trackPurchaseEvent(skuDetailsJson, purchaseDataJson, dataSignature);


        // 您的购买代码
        // ...
      }
      catch (Exception ignored)
      {
      }
   }
}
...
// ...
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
{
    super.onActivityResult(requestCode, resultCode, data)
    // Checking if the request code is PURCHASE_REQUEST_CODE
    if (PURCHASE_REQUEST_CODE == requestCode && RESULT_OK == resultCode && data != null)
    {
        try
        {
            val dataSignature = data.getStringExtra("INAPP_DATA_SIGNATURE") ?: return
            val purchaseData = data.getStringExtra("INAPP_PURCHASE_DATA") ?: return

            // 自己获取skuDetails
            val skuDetailsJson = obtainSkuDetailJson(purchaseData)

            val purchaseDataJson = JSONObject(purchaseData)

            MyTracker.trackPurchaseEvent(skuDetailsJson, purchaseDataJson, dataSignature)
        }
        catch (_: Exception)
        {
        }
    }
}
// ...
companion object
{
    const val PURCHASE_REQUEST_CODE = 1001
}
// ...

获取instanceId

设备ID instanceId是应用程序首次启动时所生成的UUID v4值,在应用(或其数据)从设备删除之前保持不变。

通过MyTracker类静态方法可以获取instanceId值(该方法不用于主线程)。

@WorkerThread
@NonNull String getInstanceId(@NonNull Context context)
@WorkerThread
fun getInstanceId(context: Context): String

It's essential to collect instanceId as soon as possible and send identifiers to your server if you use these IDs for work with S2S API.

Instead of instanceId you can use any other device ID: gaid, androidId, appSetId, and/or the user identifier customUserID (in this case, S2S data will generate stats on users). Learn more

深层链接

深层链接 允许在应用启动时向该应用发送附加参数(选项)。这些参数(选项)可用于转换到特定的应用程序界面。

延迟深度链接 允许在安装后首次启动时将附加参数(选项)传送到应用程序。这些参数(选项)的用法跟常规深层链接相同。

有关支持不同类型的深层链接以及集成所需步骤的详细信息,您可以参见我们的说明书 — 深层链接设置

为了支持深层链接,在支持深层链接(diplink)的应用程序的每个活动(activity)中,以及在onCreate和onNewIntent方法中需要调用handleDeeplink方法。

public class SomeActivity extends Activity
{
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate();
        // ...
        String deeplink = MyTracker.handleDeeplink(getIntent());
        if(deeplink != null)
        {
            // 深层链接处理
        }
    }


    @Override
    protected void onNewIntent(Intent intent)
    {
        super.onNewIntent(intent);
        // ...
        String deeplink = MyTracker.handleDeeplink(intent);
        if(deeplink != null)
        {
            // 深层链接处理
        }
    }
}
class SomeActivity : Activity()
{
    override fun onCreate(savedInstanceState: Bundle?)
    {
        super.onCreate(savedInstanceState)
        // ...
        val deeplink = MyTracker.handleDeeplink(intent)
        if (deeplink != null)
        {
            // ...
            // 深层链接处理
            // ...
        }
    }

    override fun onNewIntent(intent: Intent?)
    {
        super.onNewIntent(intent)
        // ...
        val deeplink = MyTracker.handleDeeplink(intent)
        if (deeplink != null)
        {
            // ...
            // 深层链接处理
            // ...
        }
    }
}

延迟深度链接

为了支持延迟深度链接,在您的应用中需要安装一个实现MyTracker.AttributionListener界面的侦听器。如果在当前安装中发现延迟深度链接,则在应用首次启动时,该侦听器仅被调用一次。包含deeplink属性的MyTrackerAttribution归因对象将作为参数被传递到onReceiveAttribution方法。为了避免在使用Intent时打开第三方应用程序,必须检查您的应用程序所有权的属性值。

public class YourApplicationClass extends Application
{
    @Override
    public void onCreate()
    {
        super.onCreate();


        // 如有需要,对跟踪器配置进行调整
        MyTrackerParams trackerParams = MyTracker.getTrackerParams();
        MyTrackerConfig trackerConfig = MyTracker.getTrackerConfig();
        // ...
        // 调整跟踪器的参数
        // ...


        // 安装用于获取延迟深度链接的侦听器
        MyTracker.setAttributionListener(new MyTracker.AttributionListener()
        {

            @Override
            public void onReceiveAttribution(MyTrackerAttribution attribution)
            {
                String deeplink = attribution.deeplink;
                // 延迟深度链接处理
                // ...
            }
        });

        // 跟踪器初始化
        MyTracker.initTracker(SDK_KEY, this);
    }
}
class YourApplicationClass : Application
{
    override fun onCreate()
    {
        super.onCreate()

        // 如有需要,对跟踪器配置进行调整
        val trackerParams = MyTracker.getTrackerParams();
        val trackerConfig = MyTracker.getTrackerConfig();
        // ...
        // 调整跟踪器的参数
        // ...

        // 安装用于获取延迟深度链接的侦听器
        MyTracker.setAttributionListener { myTrackerAttribution ->
            val deeplink = myTrackerAttribution.deeplink
            // ...
            // 延迟深度链接处理
            // ...
        }

        // 跟踪器初始化
        MyTracker.initTracker(SDK_KEY, this)
    }
}

如果需要,在安装侦听器时您可以通过setAttributionListener(AttributionListener attributionListener, Handler handler)方法设置侦听器执行方法的Handler。如果安装侦听器时没有设置handler,则onReceiveAttribution方法将被调用于主线程。