Create triggered tasks (client-side)
1. Feature overview
In server-side triggered operation tasks, the timeliness of reporting data to the server makes it hard to cover scenarios in weakly connected games that require trigger responses within seconds. Therefore, starting from version 4.4, the Engage module builds on the capabilities of the ThinkingData SDK to offer "client-side triggered tasks". They support millisecond-level triggering in in-app scenarios such as new user registration and character creation, as well as real-time A/B split-flow.
In addition, the Engage module communicates with your app directly through the client SDK, so you can deliver operation task parameters without developing an extra webhook service channel.
- Data flow path
2. Typical scenarios
| Scenario | Scenario description | Trigger rules |
|---|---|---|
New users - Onboarding A/B test | Run A/B tests on different onboarding flows for new users, then roll out the best-performing onboarding strategy to all users | When the user launches the game and a user ID is generated, the app launches successfully (the game finishes loading), or the user creates a character or registers an account, the onboarding flow group strategy is delivered immediately |
Resource gift packs during or after a match | For card and board games where players can go bankrupt on "tokens", push a "token" resource gift pack immediately when a player goes bankrupt during a match or at settlement | In-match resource changes: during a match, the check is usually on the change in item amount (a single deduction exceeds the current item balance); at settlement, the check is usually on the resulting value (<=0 or not enough for the entry ticket of this type of match) |
| For numeric progression games, push the resource gift pack needed for progression on the level settlement page immediately after a player fails a level (each time) consecutively | After each run of consecutive failures, push different resource gift packs based on the player's progression lines (if the player qualifies for gift packs of multiple progression lines at the same time, priority logic applies) | |
Weakly connected products | For some weakly connected products, changing client configurations requires a new release. You can use the client SDK for hot-update releases instead (the client pulls actively at launch or when the user logs in again) Common scenarios include pop-ups, resource slots, and scrolling marquees. | At app launch, or on other client behavior events |
3. Integration process
- Confirm the integration scenario: Plan the business scenarios that you want to address with client-side triggering, such as gift packs and onboarding A/B tests. After you confirm the scenarios, you can contact your ThinkingAI account manager for help with the rest of the integration.
- Integrate the SDK: For details, see the Client-triggered technical integration guide. iOS, Android, and mini game platforms are supported.
- Create and test a client channel: Open the AE Engage module, go to the Settings > Channel Settings > Client Channel page, and create a client channel. For details, see Client channel settings.
- Create a task: After the channel is connected, go to the operation task creation page. You can then customize the trigger rules and push content based on your business needs.
To use client-side triggered tasks, you need to integrate the ThinkingData SDK. Some trigger processing capabilities require a minimum SDK version, so confirm the type and version of the SDK that you have integrated before you use them. For details, see Section 6 of this chapter, SDK version support.
4. Create a client-side triggered task
Entry: Go to Engage > Operation Tasks > Create task > Select the Channel Type > Client-side Reach > Select a channel to open the operation task editing page.
4.1 Push timing
Client-side triggered tasks currently support two push types, Trigger - Completed A and Trigger - Completed A but not B, and three trigger counting modes: Each time completed, Each time continuously completed, and Each time completed in turn.
Pushes are sent immediately after a user completes the specified behavior event or behavior sequence. For example, when a player reaches level 50, a level-50 limited-time gift pack is triggered.
Client-side trigger rules only support trigger calculation on events collected by the client, and don't support events marked as updatable events or first events.
4.1.1 Trigger - Completed A — Each time completed
Each time completed: A push is triggered each time the user accumulates completions of a behavior within the task schedule
Example: Push a discount coupon each time a user completes two top-up events
- Within the selected start and end time, pushes can be sent after counting each time the user accumulates completions of a behavior, by day, week, month, or over the whole period
- Trigger rules based on multiple occurrences of a single event are supported, as well as filters on behavior event properties
- You can customize daily, weekly, or monthly start and end times. For example, 5:00 to 5:00 the next day counts as one day, and Wednesday 5:00 to the next Wednesday 5:00 counts as one week
- If you set the trigger condition to Each time completed with Condition 1 or Condition 2, you can choose whether the calculation windows of the other conditions close when any one of the conditions is triggered.
4.1.2 Trigger - Completed A — Each time continuously completed
Each time continuously completed: A push is triggered each time the user consecutively completes an event multiple times within the task schedule without doing another event in between (you can set this with Add 'Have Not Done Between').
Example: Push a gift pack to users who fail to level up twice in a row within 2 hours without topping up in between
- Within the selected start and end time, pushes can be sent after counting each time the user consecutively completes the specified event multiple times, by day, week, month, or over the whole period
- Trigger rules based on multiple occurrences of a single event are supported, as well as filters on behavior event properties
- You can add a Constant property value, a time window, and a Have not done event
- You can customize daily, weekly, or monthly start and end times. For example, 5:00 to 5:00 the next day counts as one day, and Wednesday 5:00 to the next Wednesday 5:00 counts as one week
4.1.3 Trigger - Completed A — Each time completed in turn
Each time completed in turn: A push is triggered each time the user completes the specified behavior sequence in order.
Example: Push a gift pack to users who complete "Log in - Gacha - Pay" in order within 2 hours
- Within the selected start and end time, pushes can be sent after counting each completion of the specified behavior sequence in order, by day, week, month, or over the whole period
- Trigger rules based on multiple events are supported, as well as filters on behavior event properties
- You can customize daily, weekly, or monthly start and end times. For example, 5:00 to 5:00 the next day counts as one day, and Wednesday 5:00 to the next Wednesday 5:00 counts as one week
4.1.4 Trigger - Completed A but not B
Pushes are sent after a user completes the specified behavior A but doesn't complete behavior B within a period of time.
For example, when a player gets a limited-time gift pack (completes A) and doesn't complete the purchase (doesn't complete B) within 0.5 hours, an in-app message is triggered to remind the player that the gift pack is about to expire.
Each time a user meets condition A, a separate observation period starts for that user to determine whether condition B is met within it. As soon as the user meets condition B in any observation period, one push is triggered and all other observation periods end immediately.
4.2 Push control
4.2.1 Task entry limits
You can use Task Entry Limits to limit the maximum number of pushes a user receives within a period of time. You can choose:
- The maximum number of pushes a user can receive within a single launch (a single launch lasts from opening the app until the user exits or kills it; leaving the app interface and going to the background still counts as the same launch)
- The maximum number of pushes a user can receive within the task schedule (for example, only once within the task schedule)
- The maximum number of pushes a user can receive within X days or weeks (a sliding window; for example, only once within 7 days means only once within the last 7*24 hours)
- The maximum number of pushes a user can receive within each X days, weeks, or months (a rolling window; for example, once per week means only once within each calendar week)
For example, an in-game event updates weekly, and the trigger rule pushes a related item once a player has played the game mode more than 30 times in a week. If you also want each player to receive only 1 push per week, select Weekly cumulative completion in the start and end time, and in Task Entry Limits, set each user to receive at most 1 push Weekly. You can also customize the first day of the week.
Client-side triggered tasks are calculated by the client SDK and only support events collected on the client. If your users log in on multiple devices, triggers and task entry limits are calculated independently on each device.
4.3 Audience
You can customize the audience, or push to all users who meet the trigger conditions.
4.3.1 Custom audience
After a user behavior triggers the task, you need to determine whether the user belongs to the audience, and push only to users who meet the audience conditions. Depending on timeliness, the audience is either calculated in real time or updated hourly.
Real-time calculated audience
-
After the trigger, whether the user belongs to the audience is calculated in real time
-
The following conditions support real-time calculation:
- The audience conditions use only user properties and cohorts that Support Real-time Calculation
- User properties that support real-time calculation: properties whose definitions don't include user tags or dimension tables that are unavailable in real time
- User cohorts that support real-time calculation: cohorts whose size doesn't exceed the specified limit (2 million users by default)
-
If the audience conditions use a user cohort that supports real-time calculation, you can click Edit rule to change how often the cohort is updated (every 12 hours by default)
Scheduled audience calculation
- Scheduled Update means that the audience is recalculated on a schedule at the specified frequency. After a behavior triggers the task, whether the user belongs to the audience is determined based on the most recent calculation result.
- When the audience conditions involve events or tags, dimension tables that don't support real-time calculation, or cohorts that exceed the specified limit, only scheduled calculation is supported.
- You can click Edit rule to change how often the audience is updated (every 12 hours by default)
Cohort updates consume computing resources. Choose an update frequency that fits your business scenario to avoid unnecessary resource usage.
4.3.2 All users
Once the trigger conditions are met, users are not filtered further. The push is sent as long as the trigger conditions are met.
4.3.3 Estimate audience size
After you set the audience conditions, you can click Estimate to estimate the number of target users and assess how many users the operation task may reach.
To keep the estimate as close to the actual value as possible, the estimate counts target users who meet the audience conditions and whose push ID for the selected channel is not empty (that is, users who can actually receive the push).
4.4 Client-side conditions
Unlike server-side triggered tasks, client-side triggered tasks can use not only AE data assets but also more timely client parameters obtained from the client. Client parameters include environment parameters that the ThinkingData SDK can obtain. You can also use the SET parameter API of the TDRemoteConfig SDK to SET in-game business parameters to the local SDK (for details, see the Client-triggered SDK integration guide ). These parameters can be used for local condition checks in triggered tasks. The process is as follows:
- Use the SDK API to SET custom parameters, and then add the custom client parameters in the AE console (for details, see Client parameters)
- Use the client parameters to configure Client-side Conditions in the operation task. These conditions are delivered directly to the client SDK. When a user behavior meets the trigger rules, the SDK immediately checks whether the parameters currently held by the client meet the conditions, which enables more real-time condition checks.
4.5 Push configuration
4.5.1 Set up an A/B test
Triggered tasks support A/B split-flow tests and horse-racing tests. For more information, see A/B testing
Client-side triggered tasks also let you select User ID (client) or Account ID as the bucket key.
4.5.2 Delivery caps
When multiple operation tasks use the same channel type (channel), you can limit the maximum number of pushes a single user receives from the same type of channel within a period of time, to avoid disturbing users too often.
4.6 Push content
Client-side triggered tasks don't support multiple languages yet. If you need multilingual pushes, contact your ThinkingAI CSM for a solution.
Based on the selected channel, you can fill in suitable message content according to your operation strategy and insert user properties to personalize the copy. You can also run a send test right away to preview and confirm the push effect, and turn on delivery caps or set a task whitelist as needed.
4.6.1 Personalized content
You can insert user properties or client parameters into the message content. Insert user properties or the client parameters that you have set as needed to personalize the push. For example, if you insert the user nickname property into the message content, the message that each user receives will include their nickname.
4.6.2 Send test
Before you submit the task for approval, you can use Send Test to preview the push content of the operation task and make sure it's correct.
Client-side triggered send tests require a test device. You can select a test device and turn on Debug mode. For how to turn on Debug mode, see the Client-triggered SDK integration guide.
You can test the trigger rules, task entry limits, client-side conditions, and push content. After you finish setting up the test content, select a test device and click Send.
4.6.3 Use trigger values
When the push type is Trigger - Completed A, you can define the statistical value of the trigger condition, or an event property value at the time of the trigger, as a field value of the push content, enabling more refined operation strategies.
Example scenarios:
- When a player fails a level consecutively, carry the corresponding level ID and dynamically deliver the matching level difficulty (as shown in the figure above)
- In games, push discount coupons for the item types players click in the shop (for example, if a player prefers item types such as skins, heroes, pets, or weapons, push discount coupons for that item type, such as skin coupons or weapon coupons)
- Count the total amount of a resource a player has consumed, and dynamically deliver resource bundle content based on that amount
- In live streaming products, when a streamer a player follows goes live, carry the streamer's ID and build the final profile page URL from it in the push content, so the player can go directly to the streamer's page
4.7 Goal settings
A conversion is counted when a reached user completes the specified event behavior. Conversions are used to evaluate the effect of the operation task.
You can set one main goal and two secondary goals at the same time.
4.8 Metric settings
You can set metrics for performance after any reach node to help evaluate the operation effect.
For details, see Task performance analysis
5. FAQ
-
Is there a limit on the number of client-side triggered operation tasks?
Limits: Each project supports 200 scheduled tasks, 30 server-side triggered tasks, and 30 client-side triggered tasks
Currently, each project supports up to 30 client-side triggered operation tasks. To raise the limit, contact Ops to change it.
-
What does the start and end time in trigger rules mean?
The start and end time limits the time range of event A. Event A occurrences outside the start and end time are not counted in the trigger rule calculation.
-
Why can't I select the operation task schedule manually?
Task Schedule represents the start and end time of the task. Because triggered tasks have delayed push settings, the task schedule is calculated automatically: task schedule = start and end time of event A + interval between events A and B + delayed push time.
-
Is a day in delayed push and in the interval between events A and B a calendar day or 24 hours?
Days, hours, and minutes are all calculated in seconds. A delay of 1 day means a delay of 24 hours, that is, 86400 seconds.
-
What is Message Type in a client parameter channel?
6. SDK version support
| Feature | Minimum TDstrategySDK version |
|---|---|
| 1.2.0 |
| 1.3.0 |
7. Available data assets
| Key step | Available assets |
|---|---|
| Push timing |
|
| Audience |
|
| Push Content |
|