The following is a step-by-step guide on how to fully integrate with ClanPlay’s system, and onboard your players effectively

API Documentation


Populated Clan – A clan is considered populated once its data is received from the
game’s server (via a Populate Payload API request) including clan & players [IDs,
names & avatars]

Synchronized Clan – Sending messages back and forth between the game’s chat and

user.cpUserId – The ClanPlay user ID


We will provide you with the following identifiers which are used for authentication and indexing
of chat communications:

a. Developer Key
b. Developer Secret
c. Game ID

Endpoints on your side

You need to provide us with one endpoint for a mobile game, two for web or PC games

Handshake Process

Web & PC Games

You can use two methods to perform the handshake between the user IDs

Integrate our javascript SDK

cp_sdk is a package we provide you to easily implement QR code in your game. The SDK contains two files: cp_sdk.js and qr_code_example.html.

Event name details
cp-qr-new-data Triggered every 20 seconds after a new QR / Code was generated.
cp-qr-request-stop Triggered after 5 times the cp-qr-new-data event fired, triggering the end of the linking attempts


Function details
init gets the cpGameId and the API version (current version is ‘v1.0’).
start gets the Developer key and starts the process of getting the QR
image and textual Code, from now on, for 5 times, the
cp-qr-new-data ​will be fired to let you know the server sent a new
stop By invoking this function the server will stop generating new tokens
and the cp-qr-new-data​ will seize.

Implement our RESTful API

The token will get revoked by the server every 20 seconds for security reasons.
After 5 attempts (per session) the server will stop producing new tokens.

Get Token
Generating a linking token using QR

Request (swagger)


200 OK



Parameter Info
qrCode The svg Object of the QR
textCode The textual code

Link userId’s

When a player scans the QR code, our server will notify your server (gameURL) to send
populate clan request ( Step 3 below) a synchronously.

Note: You need to validate the request using C lanPlay’s signature algorithm

Request (swagger)

Method: POST



Parameter Info
userId The developer’s ID for a unique user
cpUserId The ID provided by ClanPlay


200 OK


Mobile Games

Setup the game client to receive our broadcast and notify your server to send populate clan request ( Step 3 below) to our server

Use our JAR library:

Function details
connectToClanPlay Broadcast request to ClanPlay app to send a broadcast
asynchronously from ClanPlay with the cpUserId (handshake)
Note: if ClanPlay isn’t installed, it will launch Google Play to install
ClanPlay and then request the handshake broadcast
getClanPlayUserId Extract the ClanPlay user ID from the handshake broadcast .

Clan Population

Send clan data to our servers.

Request ( swagger )

Parameter Info
cpUserId ClanPlay’s identifier for users
userId game’s user id
image URL or a base64 string (for example players avatars)
users array of clan members IDs

Method: Post
Header: CP-Signature



200 OK

Messages Sync from ClanPlay to You

Syncing messages to your server using the a piUri endpoint.


URL: apiUri

Method: POST

Header: CP-Signature


200 OK

Messages Sync from You to ClanPlay

Syncing messages to our server.

Request ( swagger )

Method: POST

Header: CP-Signature



200 OK

Signature Algorithm

digest = HMAC (′SHA256′, Developer secret, base64 (JSON.stringify (message)))

Node.js example


On-boarding Your Players to ClanPlay

Incentivized On-Boarding

These are suggested guidelines on how to encourage your players into using ClanPlay so you can better connect with them

When should you show the Link CP button?

Players should be presented with the option to link ClanPlay after they’ve joined a clan


The “Link CP” button should be accessible from a chat-related area in the game

After clicking “Link CP” players should be presented with information about ClanPlay before going to the store to download the app, for example:

Incentivized Campaigns

Incentives for Players

Players respond greatly to hard and even soft currency incentives for linking their ClanPlay account, try incorporating this as an advanced step in your tutorial

Incentives for Clans

The next step would be to harness clan leaders to promote ClanPlay among their mates, here is a possible rewards structure

–  1st reward – 10 Clan mates have linked ClanPlay

–  2nd reward – 20 Clan mates have linked ClanPlay

–  Etc.

Download Assets

Please Click Here to download buttons and assets in both vector and .png file format



We will publish periodical best practices around on-boarding players to ClanPlay

Suggest Edit