Achievements Introduction

The Achievements service allows you to configure and release game achievements on the Developer Center. Players can unlock the achievements you configure as they play your game. Those who unlock all of your game’s achievements can also earn a Platinum Achievement.

Our Benefits

For game developers:

• Reduce development costs: Developers don’t have to build the low-level logic of an achievement system themselves. They can release an achievement system in their games by following a simple setup process.
• Increase customer lifecycle value: Improve player engagement by creating a user growth system and incentivizing players as they progress through your game.
• Enable data analysis: Developers can evaluate the difficulty of the games they create by looking at the data collected by the achievement system.

For players:

• Enhance the game experience: Players will enjoy your game more when you add fun and challenging achievements to your game.
• Evoke emotions: By instilling a sense of honor and a desire to collect, players will be more likely to stick with your game.

Glossary

Overview

Term	Definition	Rules
Achievement ID	A unique identifier used to report the achievement progress to the SDK. You can customize the achievement ID of an achievement.	Can only contain letters and numbers and cannot be longer than 100 characters.
Name	A short name for the achievement, such as “Experienced Driver”.	Can be up to 80 characters long.
Description	A short description of the achievement used to tell players how to unlock it, such as “Avoid 10 obstacles in a row”.	Can be up to 400 characters long.
Icon	A square icon to illustrate the achievement.	Upload a 512×512 color image in PNG or JPG format. TDS will automatically generate a grayscale variant that will be displayed if the achievement hasn’t been unlocked yet.
Initial Status	The initial status of the achievement. Can be either hidden or displayed.	Cannot be changed once the achievement is released.
Hidden Achievement	Players cannot see the achievement details.	If selected, TDS will provide a special description and icon for the achievement if it hasn’t been unlocked yet.
Displayed Achievement	Players can see the achievement details.	This is the default option. If selected, the achievement description will be visible to everyone.
Category	The category of a normal achievement.	A normal achievement can only have one category. You cannot change the category of an achievement unless it is unreleased.
Main Achievements	One of the two categories of achievements, containing all the achievements for the initial release of the game.	In most cases, there should be at least 10 achievements for a game. The number of main achievements is fixed for the lifetime of a game.
DLC Achievements	One of the two categories of achievements that includes the achievements that come with the game’s DLCs.	There is no limit to the number of DLC achievements that can be created for a game.

Accumulation Achievement

Accumulation achievements allow the player to incrementally approach the goals for unlocking achievements over time. As the player works toward the goals, your game can continuously report the progress to TDS so that TDS can keep track of the progress and send notifications to your game when certain achievements are unlocked. Your game can then notify the player that they have unlocked the achievements.

Configuring steps: When you create an accumulation achievement, you must specify the number of steps required to unlock the achievement (between 2 and 100,000,000). The achievement is unlocked for a player when they complete the steps required for the achievement, even if the achievement is hidden. TDS keeps track of the steps a player completes for each achievement, so you don’t have to.

Steps cannot be reset: Steps for an accumulation achievement accumulate over time and cannot be deleted or reset in-game. An example of a proper accumulation achievement is “Win 20 games”, while “Win 5 games in a row” is not an accumulation achievement because the progress is reset when the player loses a game. Similarly, “Own 2,000 coins” cannot be an accumulation achievement because players can spend coins as well as earn them. You could, however, set up the latter two achievements as basic achievements and have them unlocked for the player as they complete them, but you’d have to keep track of the progress yourself.

Rarity

This is the percentage of players who have unlocked the achievement. The lower the number, the rarer the achievement.

Rarity = Number of players who have unlocked the achievement / Number of players who have initialized the achievement

• 50% ≤ Common ≤ 100%
• 10% ≤ Uncommon < 50%
• 1% ≤ Rare < 10%
• Ultra Rare < 1%

The image below shows the different rarity levels:

Unlock Status

The unlock status of an achievement is updated when the player reaches the goal you configured for the achievement.

• Locked: The default status of an achievement, meaning that the player hasn’t unlocked it yet.
• Unlocked: The player has already unlocked the achievement. There are two cases:
  • Basic achievement: The status of the achievement becomes Unlocked when the player reaches the goal.
  • Accumulation achievement: A percentage is displayed to indicate how many steps the player has completed. Once all the steps have been completed, the status of the achievement becomes Unlocked.

The image below shows the different unlock statuses an achievement can have:

Platinum Achievement

For quality games, if a player unlocks all the Main Achievements, they will also unlock the Platinum Achievement.

Main Achievements only include those that have been released.

Features

Create Basic Achievements

To create an achievement for your game, go to Developer Center > Game Services > Cloud Services > Achievements and click on Create.

After filling in all the information, click on Save. The status of the achievement will change to Ready.

Edit Basic Achievements

To edit an existing achievement before releasing all of your achievements, click on Edit. You will see an interface similar to the one used to create an achievement. Here you can edit the details of the achievement.

Once achievements are released, each achievement’s Achievement ID, Accumulation Achievement, Category, and Initial Status settings cannot be changed anymore.

Release Basic Achievements

Your achievements will remain in Ready status while you are still editing them. Once you have at least 5 normal achievements and have tested them all, you can release them by clicking on Release Normal Achievement. Please be careful as this will release all achievements to the production environment.

Delete/Reset Achievements

Before releasing achievements, you can delete or reset the progress of an achievement using the buttons at the end of the achievement entry.

Once achievements are released, they cannot be deleted or reset.

Apply for a Platinum Achievement

To ensure the quality of Platinum Achievements, our reviewers will evaluate the quality of your game when you apply for a Platinum Achievement for it. Your game will only qualify for a Platinum Achievement if our reviewers determine that your game is of above-average quality.

Create a Platinum Achievement

Once your game qualifies for a Platinum Achievement, you can click on Create to create a Platinum Achievement. A Platinum Achievement requires an icon, name, and description.

Release a Platinum Achievement

To ensure that your game’s Platinum Achievement is challenging enough, you will not be able to release the Platinum Achievement until you have at least 10 Main Achievements. Keep in mind that once the Platinum Achievement is released, you will no longer be able to create Main Achievements for your game. You will only be able to create DLC Achievements.

Languages

To set up multiple languages, go to Developer Center > Game Services > Configuration and click on Languages.

In the pop-up window, select the languages you want to use for the achievements in your game, and then click on Confirm. You can remove any added languages from the list on the right.

Once you have completed the above steps, you can click on the + icon in the achievement editing window and select the languages you have added. You will then be able to set up different languages for the Name and Description. The icon and the other configurations will be the same for all the languages and you won’t need to fill them in again.

Displaying Achievements in Game

• TapSDK: Using the user interface provided by the TapSDK, players can view their unlocked and locked achievements by tapping a button provided by your game.
• API: You can also choose to implement your own user interface and access the achievement data through our API.

In-Game Toasts

• When the player performs an action that unlocks one or more achievements, a toast will appear at the top area of the screen. Only one achievement can be displayed at a time. Additional achievements will be queued and displayed one at a time.
• You can choose whether to show or hide the achievements page and the toasts.

Displaying Achievements on TapTap

• If you use TapTap Login (with game released on TapTap): Players logged in with TapTap Login can view their unlocked and locked achievements under “TapTap app > Profile > About”.
• If you don’t use TapTap Login: If your game has its own account system, you’ll need to create a feature that links a player’s account to their TapTap account and syncs their achievements to their TapTap account.
• At this time, only games released in the Mainland China region can have achievements displayed on TapTap.

tip

Two scenarios for linking TapTap accounts

• Scenario 1: The user has an account created without TapTap Login (Account A) and a TapTap account that hasn’t been used to log in to the game. Now the game would be able to link the two accounts. Both accounts have the same TDS user ID and the TapTap account would display Account A’s achievements.
• Scenario 2: The user has an account created without TapTap Login (Account A) and a TapTap account that has already been used to log in to the game (Account B). Currently, the TapTap account shows the achievements of Account B. In order for the TapTap account to show the achievements of Account A, your game must provide a feature that allows the user to unlink Account B from the TapTap account and then link Account A to the TapTap account.

Integrating the Service

Getting Started

1. Become a TapTap developer;
2. Create your game in the TapTap Developer Center and enable “TDS Authentication” for the game;
3. Request to enable the Achievements service by submitting a ticket. To allow sub-accounts to have access to the service, go to “Manage Permissions” and give the “Game Administrator” permission to the accounts;
4. Download the TapSDK (v3.2.0 or higher) and integrate it into the game.

Workflow

Developer Guide

See Achievements > Guide.

Testing

1. After you have added all the achievements for your game, you can set some users as testers for the production environment;
2. The testers will be able to test the achievements with the Ready status;
3. You can reset the achievement data at any time during testing;
4. If the achievement data is not reset before you release your game, the data will be transferred to the production environment and mixed with the data generated by other users. It’s up to you if you want to keep the data after testing.

note

To add testers and have them test the achievements with the Ready status, please contact the TDS technical support team by opening a ticket on the Developer Center. In the ticket, please provide the Client ID of the application and the Object ID returned after the test account implements TapTap Login.

FAQ

Can I still apply for a Platinum Achievement after releasing my game?

Yes. You can apply for a Platinum Achievement either before or after you release your game.

Can I release new achievements while my Platinum Achievement application is being reviewed?

Yes. Applying for and creating a Platinum Achievement doesn’t prevent you from releasing other achievements.

If a player has already earned all the achievements before my Platinum Achievement application is approved, will they still receive the Platinum Achievement?

Yes. The player will automatically receive the Platinum Achievement.

If my game already uses its own account system or third-party login, how can I integrate TDS Authentication into my game?

For existing users, you can let them log in with their existing accounts and then invoke the TapSDK’s account linking interface to link those accounts to TapTap. The players will then have their IDs created with TDS Authentication. The TapSDK will then be able to determine the identity of each player using the TDS User IDs. For new users, you can just let them log in with TapTap without going through these steps.

If I integrate the Achievements service into my existing game, will players still get the achievements they’re supposed to get?

There are two ways to award achievements to users of your existing game:

• Sync the expected achievement data with the Achievements service using our API.
• If your game already tracks the achievements your players have earned, you can convert those achievements to the appropriate Achievement IDs and submit them all at once with the SDK when it’s convenient (you may want to temporarily turn off toasts so the players don’t see them).

If a player already has the Platinum Achievement and I add a new achievement, will the player lose the Platinum Achievement?

No. The Platinum Achievement is only dependent on main achievements. The achievements you create after the Platinum Achievement will be DLC achievements, which won’t affect the Platinum Achievement.

If a player can create multiple profiles in my game and earn achievements multiple times, what would happen when I submit the same achievements to the SDK?

Each TapTap account can only receive each achievement once, so it won’t be possible for a player to receive the same achievement multiple times.

I’m getting Empty sign or session when invoking the interface for initializing the achievement data. What could be causing this?

As the Achievements service is based on TDS Authentication (TDSUser), please make sure that you have integrated TDS Authentication into your game and instantiated the TDSUser object before initializing the achievements data ([TapAchievement initData];). If TDSUser is empty, you will see Empty sign or session.