Server Integration
<p>[TOC]</p>
<h2>Important matters</h2>
<ol>
<li>
<p>the document was written for online games or application developers to dock the SDK server.</p>
</li>
<li>After accessing the client SDK, please contact us if you encounter any problems accessing <a href="https://www.showdoc.cc/mssdk?page_id=2615409307929897">the document</a>.</li>
</ol>
<h2>1. Introduction</h2>
<p>This document describes the process by which developers access the <code>Ledou SDK</code> server. The readers of this document are the server developers of Android and iOS SDKs connected to the fun client SDK.</p>
<h2>2. Server callback guide</h2>
<h3>2.1 Login validity verification (required)</h3>
<h4>2.1.1 Login callback process</h4>
<p><img src="https://github.com/veryitman/MSSDKResource/blob/mark-feature/Server/guide_en_01.png?raw=true" alt="" /></p>
<p>After the client logs in successfully, the game server needs to call the authentication interface to the SDK server, and pass the openid, appkey, sessionid, and Signature to the SDK server.</p>
<p>main purpose:</p>
<ul>
<li>
<p>In order to verify that the session id has expired.</p>
</li>
<li>Prevent phishing malicious programs.</li>
</ul>
<h4>2.1.2 Login Authentication Interface</h4>
<ul>
<li>
<p>Call the interface: <a href="http://internal-gw.uu.cc/internal-gateway/ms-public-oauth2/sdk_/oauth/checkSession">http://internal-gw.uu.cc/internal-gateway/ms-public-oauth2/sdk_/oauth/checkSession</a></p>
</li>
<li>
<p>Request method: POST</p>
</li>
<li>Request header parameters as shown in the following table:</li>
</ul>
<table>
<thead>
<tr>
<th>Pamameter Name</th>
<th>description</th>
<th>type</th>
<th>Required or not</th>
<th>Participate in signature or not</th>
</tr>
</thead>
<tbody>
<tr>
<td>Content-Type</td>
<td>application/json</td>
<td>String</td>
<td>yes</td>
<td>no</td>
</tr>
<tr>
<td>User-Agent</td>
<td>platform:CP;channel:CP;appVersion:1.0.0;package:com.cp.sdk;sdkVersion:1.0.0;sdkName:MSSDK;networkType:WiFi;deviceBrand:common;deviceId:00000000;localTime:2019-01-01 00:00:00</td>
<td>String</td>
<td>yes</td>
<td>no</td>
</tr>
<tr>
<td>Accept-Language</td>
<td>zh_CN</td>
<td>String</td>
<td>yes</td>
<td>no</td>
</tr>
<tr>
<td>AppKey</td>
<td>appKey value</td>
<td>String</td>
<td>yes</td>
<td>yes</td>
</tr>
<tr>
<td>Nonce</td>
<td>Random string UUID</td>
<td>String</td>
<td>yes</td>
<td>yes</td>
</tr>
<tr>
<td>Signature</td>
<td>Request signature, used to verify the legality of this request, the user needs to calculate according to the actual input parameters. See [Signature Description]</td>
<td>String</td>
<td>yes</td>
<td>no</td>
</tr>
<tr>
<td>Timestamp</td>
<td>The current UNIX timestamp, which records when the API request was initiated. Accurate to milliseconds</td>
<td>String</td>
<td>yes</td>
<td>yes</td>
</tr>
</tbody>
</table>
<ul>
<li>Request body parameters as shown in the following table:</li>
</ul>
<table>
<thead>
<tr>
<th>Pamameter Name</th>
<th>description</th>
<th>type</th>
<th>Required or not</th>
<th>signature or not</th>
</tr>
</thead>
<tbody>
<tr>
<td>appkey</td>
<td>appkey value</td>
<td>String</td>
<td>yes</td>
<td>是yes</td>
</tr>
<tr>
<td>openId</td>
<td>openid</td>
<td>String</td>
<td>yes</td>
<td>yes</td>
</tr>
<tr>
<td>sessionId</td>
<td>session id</td>
<td>String</td>
<td>yes</td>
<td>yes</td>
</tr>
</tbody>
</table>
<ul>
<li>example</li>
</ul>
<pre><code class="language-json">{
"sessionId":"c0a2296d9195572df7275f297b0ef525",
"openId":"a1eedfe67d69234a663e93aa5035ee7aa2628a8278ba0cb2da0a4438db2a14ec",
" appkey ":" 10001_LsP2XAYmBF6jHXTPOMZO "
}</code></pre>
<p><strong>Note: The value of openId, sessionId is obtained in the callback interface that the client logs in successfully. The specific acquisition method refers to the client access document and informs the game server. The sessionid is valid for 10 minutes and cannot be verified after the verification succeeds.
The parameter name should be strictly in the same case. </strong></p>
<ul>
<li>return results</li>
</ul>
<p>The verification succeeds and returns the openId, playerId, sessionId of the current session.</p>
<pre><code class="language-json">{
"code": 0,
"desc": "success",
"result": {
"encrypt": "NONE",
"data": {
"openId": "d70b36b916ae734ec8a3965f70bf0ea6",
"sessionId": "54aa52c74911d0d1450d4be6076d0242",
"playerId": 3800793368
}
}
}</code></pre>
<ul>
<li>Error code</li>
</ul>
<table>
<thead>
<tr>
<th>Error Code</th>
<th>reason</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>success</td>
</tr>
<tr>
<td>0010002</td>
<td>Signature error</td>
</tr>
<tr>
<td>0010001</td>
<td>appkey is wrong</td>
</tr>
<tr>
<td>011118</td>
<td>Sessionid does not exist</td>
</tr>
<tr>
<td>011117</td>
<td>Invalid sessionid</td>
</tr>
</tbody>
</table>
<p><strong>Signature Description: </strong></p>
<ol>
<li>Sort all request keys in ascending order by parameter name. (The so-called lexicographic order is sorted, intuitively sorted as if the words are arranged in the dictionary, in the order of increasing order in the alphabet or number table, that is, the first "letter" is considered first, and the second is considered in the same case. "letters", and so on.)</li>
</ol>
<p>After the parameters are sorted, the string is spliced, and the request parameters sorted in the previous step are formatted into the form of "parameter name" = "parameter value":</p>
<pre><code>Key1=value1& Key2=value2& Key3=value3&…………</code></pre>
<ol>
<li>Splicing the final signature string and splicing the key appSecrect before and after the string</li>
</ol>
<pre><code>appSecrect& Key1=value1& Key2=value2& Key3=value3&………& appSecrect</code></pre>
<p>Note: For post requests, the key is fixed to "requestBody" and value is the entire body of the request.</p>
<p>For example: the body of the post</p>
<pre><code>{"openId":"8ba49d502895d521e7c29885597218d7","sessionId":"2fe410d9fc9f708f77000eab113aaa0a","appkey":"LsP2XAYmBF6jHXTPOMZO"}</code></pre>
<p>The parameter dictionary is sorted and sorted before and after the appSecrect (JSxPpoOzc9de9gC2wiSt)</p>
<pre><code>JSxPpoOzc9de9gC2wiSt&AppKey=LsP2XAYmBF6jHXTPOMZO&Nonce=123456&Timestamp=201910101&requestBody={"openId":"8ba49d502895d521e7c29885597218d7","sessionId":"2fe410d9fc9f708f77000eab113aaa0a","appkey":"LsP2XAYmBF6jHXTPOMZO"}&JSxPpoOzc9de9gC2wiSt</code></pre>
<p>3, md5 generate signature string (32-bit lowercase)</p>
<p>md5(appSecrect& Key1=value1& Key2=value2& Key3=value3&………& appSecrect)</p>
<pre><code>ee427fc6c0afad74c6116aad13be0b68</code></pre>
<p><strong>Precautions</strong>:</p>
<ol>
<li>appkey, appSecrect is the key pair assigned to the game</li>
</ol>
<p>Microservices business console address: <a href="http://biz.cloud.idreamsky.com">http://biz.cloud.idreamsky.com</a>, create an app to get the corresponding appkey, appSecrect</p>
<h3>2.2 Order Payment Status Notification (Required)</h3>
<h4>2.2.1 Order Payment Status Notification Process</h4>
<p><img src="https://github.com/veryitman/MSSDKResource/blob/mark-feature/Server/guide_en_01.png?raw=true" alt="" /></p>
<p>The refill interface requires the <code>server to server</code> call method.
The main purpose is to listen to the status of the order to the game server.
The notification game server contains: order number, openId, recharge amount, actual arrival amount, attach (transparent parameter).
After receiving the notification, the game server returns the correct data and issues the corresponding item to the player.
<strong>note</strong>:
The game needs to first configure the payment callback address on the music service console.
Microservice service console address: <a href="http://biz.cloud.idreamsky.com">http://biz.cloud.idreamsky.com</a>, enter the payment module under the corresponding application configuration</p>
<h4>2.2.2 Payment callback address</h4>
<p>The game party provides a callback interface, which will be called after the player has paid for the game to notify the game service to issue the item.</p>
<ul>
<li>Method: POST</li>
<li>Request header:</li>
</ul>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>description</th>
<th>type</th>
<th>Required or not</th>
</tr>
</thead>
<tbody>
<tr>
<td>Nonce</td>
<td>random string</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>Timestamp</td>
<td>Timestamp (ms)</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>Signature</td>
<td>signature</td>
<td>String</td>
<td>yes</td>
</tr>
</tbody>
</table>
<ul>
<li>body parameter:</li>
</ul>
<table>
<thead>
<tr>
<th>Parameter Name</th>
<th>description</th>
<th>type</th>
<th>Required or not</th>
</tr>
</thead>
<tbody>
<tr>
<td>appId</td>
<td>APPID</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>resultCode</td>
<td>SUCCESS/FAIL</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>totalAmount</td>
<td>total amount</td>
<td>BigDecimal</td>
<td>yes</td>
</tr>
<tr>
<td>currency</td>
<td>Currency(default CNY=RMB)</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>payAmount</td>
<td>pay money(yuan)</td>
<td>BigDecimal</td>
<td>yes</td>
</tr>
<tr>
<td>payCurrency</td>
<td>pay Currency(default CNY=RMB)</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>payTime</td>
<td>pay time(format:yyyy-MM-dd HH:mm:ss)</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>payOrderNo</td>
<td>order number for ledou</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>outTradeNo</td>
<td>Merchant number</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>openId</td>
<td>user id</td>
<td>String</td>
<td>yes,but the value may be empty</td>
</tr>
<tr>
<td>playerId</td>
<td>CP specify player's id</td>
<td>String</td>
<td>yes</td>
</tr>
<tr>
<td>attach</td>
<td>passthrough field</td>
<td>String</td>
<td>yes,but the value may be empty</td>
</tr>
</tbody>
</table>
<p>The above parameters are submitted in the past by json data in POST mode. The signature rules are as follows:</p>
<ol>
<li>
<p>All the parameters of the request header and the request body are in the key=value mode. Note: the request body is requestBody={...}</p>
</li>
<li>
<p>Sort all the keys in ascending order by dictionary. The sorted format is key1=value1&key2=value2&...</p>
</li>
<li>
<p>splicing the sorted string before and after appSecret (provided by music)</p>
</li>
<li>The source string obtained in the second step is signed to obtain a 32-bit lowercase MD5 signature string.</li>
</ol>
<p>md5(appSecrect&Key=value&requestBody={...}&appSecrect)</p>
<ul>
<li>Signature example</li>
</ul>
<p>Request header</p>
<p>Nonce : 606130559785107456
Timestamp : 1565166201849
Signature : 62794302863fc9142bb320b3485539b3</p>
<p>1, request body (JSON format)</p>
<pre><code>{"totalAmount":6,"payAmount":6,"payOrderNo":"DEV100011907291854200001","openId":"2088622470922842","appId":"10001","outTradeNo":"10255575554140001","resultCode":"SUCCESS","attach":"2495359b-e4d7-46eb-8270-9b387d6b023a","currency":"CNY"}</code></pre>
<p>2, the parameter dictionary is sorted before and after the string is added with appSecrect (JSxPpoOzc9de9gC2wiSt)</p>
<pre><code>JSxPpoOzc9de9gC2wiSt&Nonce=606130559785107456&Timestamp=1565166201849&requestBody={"totalAmount":6,"payAmount":6,"payOrderNo":"DEV100011907291854200001","openId":"2088622470922842","appId":"10001","outTradeNo":"10255575554140001","resultCode":"SUCCESS","attach":"2495359b-e4d7-46eb-8270-9b387d6b023a","currency":"CNY"}&JSxPpoOzc9de9gC2wiSt</code></pre>
<p>3, After the MD5 encryption of the data, the <strong>32-bit lowercase encryption string is obtained</strong>:</p>
<pre><code>86547d7998c553ac57f1f4dfb4aa2c34</code></pre>
<p>The game server returns the result (json format):</p>
<pre><code class="language-json">{"returnCode":"xxx","returnMsg":"xxx"}</code></pre>
<p>Parameter Description:</p>
<ul>
<li>
<p>returnCode: <code>SUCCESS</code> or <code>FAIL</code></p>
</li>
<li>returnMsg: information description</li>
</ul>
<p><code>SUCCESS</code>: indicates that the game server has successfully processed the order logic, and the music server no longer initiates notifications.</p>
<p><code>FAIL</code>: Indicates that the logic processing of the game server failed this time. You also need to receive the next notification from the music server to process it again.</p>
<p><code>FAIL</code>: or no return (timeout): The music server will make a reissue of the reissue, and a total of eight notifications will be sent. The notification frequency is 5s, 15s, 1 minute, 5 minutes, 10 minutes, 20 minutes, 30 minutes. 1 hour, 8 times will not be notified.</p>
<p><strong>Precautions:</strong></p>
<ol>
<li>
<p>The parameters participating in the signature strictly use the type of the request form. Please do not convert the type at will.</p>
</li>
<li>
<p>the request header except <strong>Signature does not participate in the signature</strong>, all other parameters participate in the signature</p>
</li>
<li>
<p>The signature value is related to the order of the parameters and the case.</p>
</li>
<li>When <code>resultCode</code> is <code>SUCCESS</code>, it means success. Other values are failures. When the game fails, the game side will not be shipped, and the music server will initiate the notification again.</li>
</ol>