1.Introduction

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

2.API Documentation

Glossary

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
ClanPlay

user.cpUserId – The ClanPlay user ID

Identifiers

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

2.1.Handshake Process

2.1.1.Web & PC Games

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

2.1.1.1.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
token.
stop By invoking this function the server will stop generating new tokens
and the cp-qr-new-data​ will seize.

2.1.1.2.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)

Response

200 OK

Body

 

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

Header

Body

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

Response

200 OK

 

2.1.2.Android Native 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 .

2.1.3.Unity Plugin integration process (Android)

Handshake process details

Handshake between ClanPlay user id and the game player id.
In order to start the handshake process, ClanPlay app sends an intent containing the ClanPlay user id. The game app sends this ClanPlay user id to the Game server and it sends the ClanPlay user id as part of the “populate clan” request to ClanPlay server.

Integration steps

1. The game app has to register a broadcastreceiver by specifying a receiver in <application> tag of AndroidManifest.xml file of application project as follows:

  • The broadcastreceiver implemented by Clanplay Unity plugin.

 

2. The game app should initialize Clanplay Unity plugin by calling the following in Clanplay.cs, as early as possible within the game:

Sample code:

Using guide

ClanPlay SDK support 2 scenarios:

1. When ClanPlay user choose to link a game from the ClanPlay app
ClanPlay app broadcast an intent to the game client.

Clanplay Unity plugin receives the ClanPlay user id from the broadcast intent, and calls the following methodin Clanplay.cs, and this is where you should place your Clanplay integration code:

 

2. When the player click on the “Link ClanPlay” button in the game app
The game app should call the method in Clanplay.cs

Sample code:

Notes

  • This method already implements the logic to handle the situation when ClanPlay app is not installed on the device, will open the market to download it.
  • ClanPlay sends a broadcast as a result of this connect request, this broadcast is handled by the game app the same as scenario 1.

2.2.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

Body

Response

200 OK

2.3.Messages Sync from ClanPlay to You

Syncing messages to your server using the a piUri endpoint.

Request

URL: apiUri

Method: POST

Header: CP-Signature

Response

200 OK

2.4.Messages Sync from You to ClanPlay

Syncing messages to our server.

Request ( swagger )

Method: POST

Header: CP-Signature

Body

Response

200 OK

2.5.Signature Algorithm

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

Node.js example

 

3.Post Integration Tests

Download this checklist

Below are tests that should be conducted after completing the integration to ensure the competency of synchronisation, they are sorted by functionality

QR Code

 Verify that you are getting a new code in each request

 Verify that your code refreshes every 20 seconds

 Perform a QR scan from ClanPlay and verify the handshake takes place

 Input the numerical code as a QR alternative and verify that a handshake takes place

Link CP Button

 Make sure you have implemented a text message to your players after they press
        the button and before they are sent to download ClanPlay

 Test the button while ClanPlay is not installed to see if it sends players to the right
        page in the App store

 Test the button while ClanPlay is installed to verify that a handshake takes place

Link Game from ClanPlay

 From within ClanPlay use the FAB button (plus button on the bottom right of the main screen)
        and select Link Game

 Tap your game to verify that a handshake takes place

Messages Exchange

Synchronized chat

  Send and receive messages to and from ClanPlay <-> clan chat in game

  Send and receive messages to and from ClanPlay <-> 1 on 1 (private) chat in game

Message Content

 Send an image in ClanPlay -> the in-game message should appear as:
       “I sent an image on ClanPlay”

 Send each of the below strings from the game and then from ClanPlay, make sure
       they are broadcasted properly to the other side:

Привет – großen – 좋은 – 是从

لقد يوم عظيم 🙂

Download this checklist

4.Privacy Paragraph

Here is a privacy paragraph you can add to your Privacy Policy:

We cooperate with ClanPlay Ltd. (“ClanPlay”), in order to enable you and other players of [the game: insert the name of the game] to communicate with players in your clans even outside [the game: insert the name of the game].

If you or other players who communicate with you within the clan choose to link the clan to ClanPlay, we will share the content of your conversation (such as text, images, photos and video) with ClanPlay.

Please note that this may occur even if only one of the players with whom you chat uses ClanPlay. You hereby agree to share information (including personally identifiable information) between us and ClanPlay, in order to enable you or other players within the clan to communicate with each other outside [the game: insert the name of the game].

Your use of ClanPlay in this manner, or interaction with the players who use it, indicates your acceptance of ClanPlay’s terms of use and privacy policy https://www.clan-play.com/privacy/ and is not subject to this privacy policy.

5.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

Where?

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:

5.1.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.

5.2.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