Skip to main content

CocosCreator

Last updated 10/05/2026
tip

Before you integrate the SDK, read Pre-integration preparation.

Platforms supported by the CocosCreator SDK: Android, iOS, HarmonyOS, Web, WeChat mini games, Alipay mini games, Taobao mini games, ByteDance mini games, OPPO mini games, Huawei quick games, vivo mini games, Xiaomi quick games, Baidu mini games, Qutoutiao mini games, Facebook mini games, and Google Play mini games.

Latest version: v3.8.0

Update time: 2026-09-16

Downloads: Source code, SDK download

Note

This document applies to v3.0.0 and later. For earlier versions, see CocosCreator Integration Guide (V2) and SDK download (v2.2.4)

1. Integrate the SDK​

Download and unzip the CocosCreator SDK

If your project is a TypeScript project, follow these steps:

  1. Put the declaration file tdanalytics.cc.d.ts in the libs directory under assets in the project root directory. If libs does not exist, create the libs directory
  2. Put the SDK file (tdanalytics.mg.cocoscreator.min.js) in the assets/Script directory

2. Initialization​

After you import the AE SDK, you can use TDAnalytics in your code:

note

When you package for the Taobao mini game platform, TDAnalytics is mounted on the window object, so you need to use var TDAnalytics = window['TDAnalytics']

// AE SDK configuration object
var config = {
  appId: "YOUR_APPID", // Project APP ID
  serverUrl: "YOUR_SERVER_URL", // Reporting URL
  autoTrack: {
    appLaunch: true, // Auto-track ta_mg_launch
    appShow: true, // Auto-track ta_mg_show
    appHide: true // Auto-track ta_mg_hide
  }
};
// Initialize
TDAnalytics.init(config);

The parameters of the AE configuration object are as follows:

  • appId: The APP ID of your project. Required. You can find it on the Project Settings page in AE

  • serverUrl: The data reporting URL. Required

  • autoTrack: Optional. Specifies whether to enable auto-tracking. Each element represents one of the following auto-tracked events. All of them are disabled by default:

    • appLaunch: Auto-tracks mini game initialization
    • appShow: Auto-tracks the mini game being launched or entering the foreground from the background
    • appHide: Auto-tracks the mini game going from the foreground to the background, and records the duration of this visit (from launch to going to the background)
Note

Before you report data, add the data transfer URL to the request list of server domain names in the development settings of the WeChat Official Accounts Platform or other platforms.

3. Common features​

Before you use the common features, we recommend that you read the user identification rules. By default, the SDK generates a random number as the distinct ID and stores it locally. Before a user logs in, the distinct ID is used as the user's identifier. Note: The distinct ID changes when the user clears the cache or switches devices.

3.1 Set the account ID​

When a user logs in, you can call login to set the user's account ID. The AE platform uses the account ID as the identifier, and the account ID you set is kept until logout is called. Calling login multiple times overwrites the previous account ID.

// The unique login identifier of the user, which corresponds to #account_id in the reported data. In this case, the value of #account_id is TA
TDAnalytics.login("TA");

This method does not upload a login event

3.2 Set super properties​

Super properties are properties that every event carries. You can call setSuperProperties to set super properties. We recommend setting super properties before you send events. Some important properties, such as a user's membership level and source channel, need to be set in every event; in this case, you can set them as super properties.

var superProperties = {
    channel : "ta", //String
    age : 1,//Number
    isSuccess : true,//Boolean
    birthday :  new Date(),//Time
    object : { key : "value" },//Object
    object_arr : [ { key : "value" } ],//Object group
    arr : [ "value" ]//Array
};
//Set super properties
TDAnalytics.setSuperProperties(superProperties);

Super properties are saved in the cache, so you don't need to call this every time the app starts. If you call setSuperProperties to upload a super property that was set before, the new value overwrites the previous one.

  • Key is the name of the property and is of the string type. It must start with a letter, can contain only digits, letters, and underscores "_", and can be up to 50 characters long. Keys are not case-sensitive; AE converts all letters to lowercase
  • Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

Event properties and user properties have the same requirements as super properties

3.3 Send events​

You can call track to upload events. We recommend setting event properties and the conditions for sending them according to the tracking plan you prepared earlier. The following example tracks a user purchasing a product:

TDAnalytics.track({
    eventName: "product_buy", // Event name
    properties: { 
        product_name: "Product Name" 
    } //Event properties
});

The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.

3.4 Set user properties​

For general user properties, you can call userSet to set them. Properties uploaded through this API overwrite the existing property values. If the user property did not exist before, it is created with the same type as the value passed in. The following example sets the user name:

//username is TA at this point
TDAnalytics.userSet({
    properties: { username: "TA" }
});
//username is AE at this point
TDAnalytics.userSet({
    properties: { username: "AE" }
});

4. Best practices​

The following sample code includes all of the operations above. We recommend using them in the following order:

var config = {
  appId: "YOUR_APPID", // Project APP ID
  serverUrl: "YOUR_SERVER_URL", // Reporting URL
  autoTrack: {
    appLaunch: true, // Auto-track ta_mg_launch
    appShow: true, // Auto-track ta_mg_show
    appHide: true // Auto-track ta_mg_hide
  }
};
//Initialize
TDAnalytics.init(config);
// The unique login identifier of the user, which corresponds to #account_id in the reported data. In this case, the value of #account_id is TA
TDAnalytics.login("TA");
//Set super properties
var superProperties = {
    channel : "ta", //String
    age : 1,//Number
    isSuccess : true,//Boolean
    birthday :  new Date(),//Time
    object : { key : "value" },//Object
    object_arr : [ { key : "value" } ],//Object group
    arr : [ "value" ]//Array
};
TDAnalytics.setSuperProperties(superProperties);
//Send an event
TDAnalytics.track({
    eventName: "product_buy", // Event name
    properties: {
        product_name: "Product Name"
    } //Event properties
});
//Set user properties
TDAnalytics.userSet({
    properties: {
        username: "AE"
    }
});
Was this page helpful?
On this page