Skip to main content
Version: v3

Billboard Guide

tip

Before integrating Billboard’s SDK into your game, please first enable the service and configure your domains according to Feature Introduction.

SDK Setup

Please download the TapSDK from the Download page and follow the instructions below to import the Billboard module to your project.

If you are building your game with Unity, you can import a .unitypackage file to your game, which includes the iOS module and the Android module. If you are building with other engines or for other platforms, you can import the iOS or Android module natively. Please refer to the documentation for iOS or Android for more information.

Unity requirement: You will need Unity 2019.4 or higher to use the SDK.

Supported OS versions:

  • Android: 5.0 and higher
  • iOS: 10.0 and higher, Xcode 14.1 or later
"dependencies":{
"com.taptap.tds.billboard": "https://github.com/TapTap/TapBillboard-Unity.git#3.28.3",
"com.taptap.tds.login":"https://github.com/TapTap/TapLogin-Unity.git#3.28.3",
"com.taptap.tds.common": "https://github.com/TapTap/TapCommon-Unity.git#3.28.3",
"com.taptap.tds.bootstrap": "https://github.com/TapTap/TapBootstrap-Unity.git#3.28.3",
"com.leancloud.realtime": "https://github.com/leancloud/csharp-sdk-upm.git#realtime-2.3.0",
"com.leancloud.storage": "https://github.com/leancloud/csharp-sdk-upm.git#storage-2.3.0",
}

Initializing the SDK

info

You can initialize the SDK using one of the following two methods.

Initializing With the TapSDK

If you have already initialized the TapSDK according to Quickstart, you will only need to import the Billboard module here and add the highlighted portions of the code below to your project.

using TapTap.Common;
using TapTap.Bootstrap;
using TapTap.Billboard;

var dimensionSet = new HashSet<KeyValuePair<string, string>>();
KeyValuePair<string, string> platformPair = new KeyValuePair<string, string>("platform", "TapTap");
KeyValuePair<string, string> locationPair = new KeyValuePair<string, string>("location", "CN");
dimensionSet.Add(platformPair);
dimensionSet.Add(locationPair);
var templateType = "navigate"; // Optional
var billboardServerUrl = "https://your-billboard-server-url"; // Developer Center > Your game > Game Services > Configuration > Domain > Billboard

var config = new TapConfig.Builder()
.ClientID("your_client_id") // Required; the Client ID obtained from the Developer Center
.ClientToken("your_client_token") // Required; the Client Token obtained from the Developer Center
.ServerURL("https://your_server_url") // Required; can be found on Developer Center > Your game > Game Services > Basic Information > Domain > Cloud Services API
.RegionType(RegionType.CN) // Optional; CN means China mainland and IO means other countries and regions
.TapBillboardConfig(dimensionSet, templateType, billboardServerUrl)
.ConfigBuilder();
TapBootstrap.Init(config);

Initializing the Billboard Service Independently

If you prefer not to initialize the TapSDK with the TapBootstrap method mentioned above and would like to only initialize the Billboard service, you can:

  • Copy the above code for initializing the TapSDK.
  • Change the last line to:
TapBillboard.Init(config);

Parameters

  • You will be providing both the API domain and the Billboard domain when initializing the SDK. See Domain for more information. Please make sure you have added your domain on Developer Center > Your game > Game Services > Configuration > Domain.
  • See Configure Properties for more information about dimensionSet. Here we are using the two default properties: Platform and Region.

  • client_id, client_token, and RegionType can be found on Developer Center > Your game > Game Services > Configuration.

Opening the Billboard

TapBillboard.OpenPanel((any, error) =>
{
if (error != null)
{
// Failed to open the billboard; see `error.code` and `error.errorDescription` for the reason
} else
{
// Billboard is now open
}
}, () => {
// Billboard is now closed
});

Obtaining Badge Statuses

Badges can be used to tell whether there are new messages. Inside the SDK, the statuses of the badges are cached. If a request is made within 5 minutes after the last request is made, the result of the last successful request will be returned.

TapBillboard.QueryBadgeDetails((badgeDetails, error) =>
{
if (error != null)
{
// Failed to obtain badge statuses; see `error.code` and `error.errorDescription` for the reason
}
else
{
// Badge statuses obtained
if (badgeDetails.showRedDot == 1) {
// New messages found
} else {
// No new messages
}
}
});

Registering Custom Event Listeners

If an announcement is configured to jump to a module in the game, or if you have added links in the content of an announcement that jumps to a module in the game, you can obtain the message with a custom event listener you set up and handle the message accordingly.

TapBillboard.RegisterCustomLinkListener(url =>
{
// The URL returned here is the same as the one configured on the Developer Center
});

Unregistering Custom Event Listeners

Use the following interface to stop listening to the custom events related to announcements:

// Registered listeners should be stored and provided here to have them unregistered
TapBillboard.UnRegisterCustomLinkListener(registerdListener);

Internationalization

You can set different languages for the Billboard service:

TapCommon.SetLanguage(TapLanguage.AUTO);

The following languages are supported:

namespace TapTap.Common
{
public enum TapLanguage
{
AUTO = 0, // Auto
ZH_HANS = 1, // Simplified Chinese
EN = 2, // English
ZH_HANT = 3, // Traditional Chinese
JA = 4, // Japanese
KO = 5, // Korean
TH = 6, // Thai
ID = 7, // Indonesian
}
}

When Auto is selected, the SDK will set the language based on the system language. If the system language is not among the supported languages listed above, the SDK will set the language according to the region configured when the SDK is initialized. If the region is China mainland, the language will be Simplified Chinese. Otherwise, the language will be English.

Error Codes

codeScenario
400An error exists in the parameters used for initializing the SDK.
403The user is not authorized to access this service. Please make sure the Billboard service has been enabled on the Developer Center.
50xThere is an internal error in our server. See description for more information.
19999An unknown error occurred. See description for more information.

REST API

Below are the REST APIs provided by the Billboard services.

Request Format

For POST

For POST and PUT requests, the request body must be in JSON and the Content-Type of the HTTP Header must be application/json.

Requests are authenticated by the key-value pairs in the HTTP Header shown in the following table:

KeyValueDescriptionSource
X-LC-Id{{appid}}The App Id (Client Id) of the current appCan be found on the Developer Center
X-LC-Sign{{appSign}}A string in the form of sign,timestamp. timestamp is the unix timestamp (UTC) of the client in milliseconds. sign is a string formed by concatenating the timestamp with the App Key (Client Token) and running it through the MD5 algorithm.See the algorithm below.

To calculate the appSign with the App Key:

md5( timestamp + App Key )
= md5(1453014943466UtOCzqb67d3sN12Kts4URwy8)
= d5bcbb897e19b2f6633c716dfdfaf9be

-H "X-LC-Sign: d5bcbb897e19b2f6633c716dfdfaf9be,1453014943466"

Besides setting the value of X-LC-Id to the Client Id in the HTTP Header, you will also need to provide the Client Id in the URL, and their values have to be the same.

You will get an HTTP 400 error if something goes wrong, like:

{
"success": false,
"data": {
"code": 0,
"error": "invalid_request",
"msg": "invalid params",
"error_description": ""
},
"now": 1659084246
}

Base URL

The Base URL for REST API requests (the {{host}} in the curl examples) is the custom API domain of your app. You can update or find it on the Developer Center. See Domain for more details.

Obtaining the Template

ParameterConstraintDescription
client_idRequiredThe Client ID found on Developer Center > Game Services > Configuration.
templateRequiredThe type of the template. For now, only Navigation Bar is supported. Use navigate for Navigation Bar and image for Poster.
curl -X GET
-H 'X-LC-Id: {{appid}}' \
-H 'X-LC-Sign: {{appSign}}' \
https://{{host}}/billboard/rest-api/v1/pattern/detail?client_id={{appid}}&template={{template}}

The response body is a JSON object containing all the parameters provided when the template is created:

{
"success": true,
"data": {
"empty_img": {
"url": "https://tds-billboard.tds1.tapfiles.cn/20220727/aWkG63mpT2WeFrtT0Dxojj4QLfabWHh3.png"
},
"highlight_text_color": "#00D9C5",
...
},
"now": 1659085552
}

Obtaining Announcements

ParameterConstraintDescription
client_idRequiredThe Client ID found on Developer Center > Game Services > Configuration.
langRequiredSee Language Codes.
templateRequiredThe type of the template. For now, only Navigation Bar is supported. Use navigate for Navigation Bar and image for Poster.
dimension_listOptional[{"PROPERTY_PARAMETER":"FIELD_PARAMETER"},...]. Example: [{"platform":"ios"},{"location":"CN"}].
typeRequiredThe type of the announcement. Use activity for Events and game for Announcements.
uuidOptionalA unique ID identifying the device. Used for analytical purposes only. Example: 4e4105c7-781e-45c0-92ea-d595c75a3c2c.
curl -X POST
-H 'X-LC-Id: {{appid}}' \
-H 'X-LC-Sign: {{appSign}}' \
-H 'Content-Type: application/json' \
-d '{
"lang":{{lang}},
"template":{{template}},
"type":{{type}},
"dimension_list":{{dimension_list}}
}' \
https://{{host}}/billboard/rest-api/v1/announcement/list?client_id={{appid}}&uuid={{uuid}}

The returned JSON object contains the announcement list, list, as well as the details of the latest announcement, lastest.

ParameterDescription
idThe ID of the announcement.
typeThe type of the announcement. Could be update, maintenance, new, activity, play_method, test, or discontinued.
expire_timeThe timestamp of the expiration time in seconds. 0 means the announcement will not expire.
short_titleThe short title.
jump_locationThe place to jump to. Could be content, link, or game.
jump_linkThe link for redirection or the parameter indicating the module in the game to jump to.
publish_timeThe timestamp of the publication time in seconds.
{
"success": true,
"data": {
"list": [
{
"id": 2,
"type": "activity",
"expire_time": 0,
"short_title": "Hello",
"jump_location": "link",
"jump_link": "https://www.taptap.cn",
"publish_time": 1659077524
},
...
],
"lastest": {
"id": 2,
"content": "This is the content.",
"short_title": "Hello",
"long_title": "Hello world!"
}
},
"now": 1659085756
}

Obtaining Announcement Details

ParameterConstraintDescription
client_idRequiredThe Client ID found on Developer Center > Game Services > Configuration.
langRequiredSee Language Codes.
idRequiredThe ID of the announcement.
uuidOptionalA unique ID identifying the device. Used for analytical purposes only. Example: 4e4105c7-781e-45c0-92ea-d595c75a3c2c.
curl -X GET
-H 'X-LC-Id: {{appid}}' \
-H 'X-LC-Sign: {{appSign}}' \
https://{{host}}/billboard/rest-api/v1/announcement/detail?client_id={{appid}}&lang={{lang}}&id={{id}}&uuid={{uuid}}

Returned JSON object

ParameterDescription
idThe ID of the announcement.
contentThe content of the announcement.
long_titleThe long title of the announcement.
short_titleThe short title of the announcement.
{
"success": true,
"data": {
"id": 82,
"content": "This is the content.",
"short_title": "This is the short title.",
"long_title": "This is the long title."
},
"now": 1659087990
}

Obtaining Badge Statuses

ParameterConstraintDescription
client_idRequiredThe Client ID found on Developer Center > Game Services > Configuration.
uuidRequiredA unique ID identifying the device. Example: 4e4105c7-781e-45c0-92ea-d595c75a3c2c.
templateRequiredThe type of the template. For now, only Navigation Bar is supported. Use navigate for Navigation Bar and image for Poster.
dimension_listOptional[{"PROPERTY_PARAMETER":"FIELD_PARAMETER"},...]. Example: [{"platform":"ios"},{"location":"CN"}].
curl -X POST \
-H 'X-LC-Id: {{appid}}' \
-H 'X-LC-Sign: {{appSign}}' \
-H 'Content-Type: application/json' \
-d '{
"uuid": {{uuid}},
"template":{{template}},
"dimension_list":{{dimension_list}}
}' \
'https://{{host}}/billboard/rest-api/v1/dot/read?client_id={{client_id}}'

Returned JSON object

ParameterDescription
show_red_dotWhether to show the badge. 0 means no and 1 means yes.
close_button_imgThe URL of the image for the close button.
{
"success": true,
"data": {
"show_red_dot": 0,
"close_button_img": "https://tds-billboard.tds1.tapfiles.cn/20220727/aMHoqDTHT4zrXYPNprkZjXkdLK6vFg8E.png"
},
"now": 1658896487
}

Updating Badge Statuses

ParameterConstraintDescription
client_idRequiredThe Client ID found on Developer Center > Game Services > Configuration.
uuidRequiredA unique ID identifying the device. Example: 4e4105c7-781e-45c0-92ea-d595c75a3c2c.
read_allRequiredWhether to mark all announcements as read. true for yes and false for no.
curl -X POST \
-H 'X-LC-Id: {{appid}}' \
-H 'X-LC-Sign: {{appSign}}' \
-H 'Content-Type: application/json' \
-d '{
"uuid": {{uuid}},
"read_all":{{read_all}}
}' \
'https://{{host}}/billboard/rest-api/v1/dot/submit?client_id={{client_id}}'

Returned JSON object

{
"success": true,
"data": {
"msg": "ok"
},
"now": 1658895192
}

Language Codes

The REST API accepts language codes defined by ISO 639-1. For example, en means English and jp means Japanese. There are a couple of exceptions:

  1. For languages not included in ISO 639-1, the language codes defined in ISO 632-2 are used. For example, fil means Filipino.
  2. When a language cannot be represented by a language code, the location code defined in ISO 3166-1 will be attached. For example, zh_CN means Simplified Chinese.

The following language codes are supported by the REST API:

CodeLanguage
zh_CNSimplified Chinese
zh_TWTraditional Chinese
en_USEnglish (US)
ja_JPJapanese
ko_KRKorean
pt_PTPortuguese
vi_VNVietnamese
hi_INHindi
id_IDIndonesian
ms_MYMalay
th_THThai
es_ESSpanish
afAfrikaans
amAmharic
bgBulgarian
caCatalan
hrCroatian
csCzech
daDanish
nlDutch
etEstonian
filFilipino
fiFinnish
frFrench
deGerman
elGreek
heHebrew
huHungarian
isIcelandic
itItalian
lvLatvian
ltLithuanian
noNorwegian
plPolish
roRomanian
ruRussian
srSerbian
skSlovak
slSlovenian
swSwahili
svSwedish
trTurkish
ukUkrainian
zuZulu

Keep in mind that some of the languages listed above are only supported by the REST API but not the client SDK.

Video Tutorials

You can refer to the video tutorial:How to Integrate Billboard Functionality in Games to learn how to access the billboard feature in Untiy project.

For more video tutorials, see Developer Academy. As the SDK features are constantly being improved, there may be inconsistencies between the video tutorials and the new SDK features, so the current documentation should prevail.