Skip to main content

Cocos2d-Lua

Last updated 10/05/2026
tip

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

The Cocos2d-Lua SDK runs on iOS and Android and is about 7.1M in size

Latest version: v2.0.2

Update time: 2024-01-19

Downloads: Source code, SDK download

Note

This document applies to v2.0.0 and later. For earlier versions, see Cocos2d-Lua Integration Guide (V1) and SDK download (v1.0.1)

1. Integrate the SDK​

  • Add the Cocos2d-Lua configuration

    • Download the Cocos2d-Lua SDK resource files, unzip them, and add TDAnalytics.lua to the src folder

  • Add the Android configuration

    • Create a libs folder in the frameworks/runtime-src/proj.android/app directory, and add TDAnalytics.aar and TDCore.aar to the libs folder
    • Add TDAnalyticsProxy.java to the frameworks/runtime-src/proj.android/app/src/org/cocos2dx/lua directory
    • Add the following configuration to CMakeLists.txt
if(ANDROID)
    list(APPEND GAME_SOURCE
        # ... Add the following code
        ${RUNTIME_SRC_ROOT}/proj.android/app/src/org/cocos2dx/lua/TDAnalyticsProxy.java
        ${RUNTIME_SRC_ROOT}/proj.android/app/libs/TDCore.aar
        ${RUNTIME_SRC_ROOT}/proj.android/app/libs/TDAnalytics.aar
        )
endif()
  • Add the following configuration to build.gradle in the frameworks/runtime-src/proj.android/app directory
dependencies {
    // Reference the .aar files
    implementation fileTree(include: ['*.jar','*.aar'], dir: 'libs')
}

  • Add the iOS configuration (Cocos2d-Lua-Community 4.x)

    • Add TDAnalyticsProxy.h, TDAnalyticsProxy.mm, and ThinkingSDK.framework to the frameworks/runtime-src/proj.ios_mac/ios directory
    • Add the following configuration to CMakeLists.txt
if(APPLE)
    if(IOS)
        list(APPEND GAME_HEADER
             # [TDAnalytics] Add the following code
             ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/TDAnalyticsProxy.h
             )
        list(APPEND GAME_SOURCE
             # [TDAnalytics] Add the following code
             ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/TDAnalyticsProxy.mm
             ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/ThinkingSDK.framework
             )
    endif()
endif()

if(IOS)
    # [TDAnalytics] Add the following code
    target_link_libraries(${APP_NAME} ${RUNTIME_SRC_ROOT}/proj.ios_mac/ios/ThinkingSDK.framework)
endif()


if(IOS)
    # [TDAnalytics] Add the following code
    set(CMAKE_EXE_LINKER_FLAGS -ObjC)
endif()

  • Add the iOS configuration (Cocos2d-Lua-Community 3.x)

    • Open the iOS project in Xcode and drag the iOS folder from the SDK directory into the Classes directory
    • In Build Setting -> Other Linker Flags, add -force_load "$(SRCROOT)/ios/ThinkingSDK.framework/ThinkingSDK" to both Debug and Release

2. Initialization​

local TDAnalytics = require("TDAnalytics")
TDAnalytics.init(APPID, SERVER_URL, TDAnalytics.debugModel.debugOff)

Parameters:

  • APPID: The APPID of your project, which you can find on the Project Settings page in AE

  • SERVER_URL: The URL that data is uploaded to

    • If you use the cloud service, enter: https://global-receiver-ta.thinkingdata.cn
    • If you use an on-premises deployment, bind a domain name to the data collection URL and configure an HTTPS certificate: https://your-domain-for-data-collection

Android 9.0 and later restrict HTTP requests by default, so make sure you use HTTPS.

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 reinstalls the app 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")

login can be called multiple times. Each call checks whether the passed account ID is the same as the previously saved ID. If it is the same, the call is ignored; otherwise, the previous ID is overwritten.

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.

local superProperties = {}
superProperties["channel"] = "ta" -- String
superProperties["age"] = 1 -- Number
superProperties["isSuccess"] = true -- Boolean
superProperties["birthday"] = os.date("%Y-%m-%d %H:%M:%S") -- Time
superProperties["object"] = { key="value" } -- Object
superProperties["object_arr"] = { { key="value" } } -- Object group
superProperties["arr"] = { "value" } -- Array
TDAnalytics.setSuperProperties(superProperties) -- Set super properties

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 Enable auto-tracking​

The following code example enables the install, start, and close events. To learn more about the SDK's auto-tracking capabilities, see Auto-tracked events

TDAnalytics.enableAutoTrack( {
    appInstall = true, 
    appStart = true, 
    appEnd = true
});

3.4 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("product_buy", {
    product_name="Product Name"
});

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.5 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 does not exist yet, it is created with the same type as the value passed in. The following example sets the user name:

-- user_name is now TA
TDAnalytics.userSet({
    user_name = "TA"
})
-- user_name is now AE
TDAnalytics.userSet({
    user_name = "AE"
})

4. Best practices​

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

-- Import TDAnalytics
local TDAnalytics = require("TDAnalytics")

if isPrivacyPolicyAccepted then -- The user has accepted the privacy policy
    -- Initialize the SDK
    TDAnalytics.init(APP_ID, SERVER_URL, TDAnalytics.debugModel.debugOff);
    --Enable auto-tracked events
    TDAnalytics.enableAutoTrack( {
        appInstall = true, 
        appStart = true, 
        appEnd = true
    });
    --If the user is logged in, you can set the user's account ID as the unique identifier
    TDAnalytics.login("TA")

    --After super properties are set, every event carries them
    local superProperties = {}
    superProperties["channel"] = "ta" -- String
    superProperties["age"] = 1 -- Number
    superProperties["isSuccess"] = true -- Boolean
    superProperties["birthday"] = os.date("%Y-%m-%d %H:%M:%S") -- Time
    superProperties["object"] = { key="value" } -- Object
    superProperties["object_arr"] = { { key="value" } } -- Object group
    superProperties["arr"] = { "value" } -- Array
    TDAnalytics.setSuperProperties(superProperties) -- Set super properties

    --Send an event
    TDAnalytics.track("product_buy", {
        product_name="Product Name"
    });

    --Set user properties
    TDAnalytics.userSet({
        user_name = "AE"
    })
end
Was this page helpful?
On this page