Pocket Games Software www.pgsoft.com PG SOFT Integration Document Seamless Mode v2.4.10
Pocket Games Software www.pgsoft.com Contents Revision History ...................................................................................................................................... 3 1 Overview........................................................................................................................................... 8 2 System Requirements....................................................................................................................... 9 2.1 Game Dimensions ...................................................................................................................... 9 2.2 Hardware ................................................................................................................................... 9 2.3 Browser ...................................................................................................................................... 9 2.4 Unsupported Browser................................................................................................................ 9 3 Launch Game .................................................................................................................................. 10 3.1 Game Authorization Modes ..................................................................................................... 10 3.1.1 HTML Scheme.................................................................................................................. 11 3.1.2 Android SDK Scheme ....................................................................................................... 24 3.1.3 iOS SDK Scheme .............................................................................................................. 34 3.1.4 API Reference .................................................................................................................. 53 3.1.5 Others .............................................................................................................................. 55 3.2 Sample Request ....................................................................................................................... 56 3.2.1 HTML Direct Launch Game Mode ................................................................................... 56 3.2.2 iFrame Mode (Recommended) ....................................................................................... 57 3.2.3 Ajax Mode (Not Recommended)..................................................................................... 60 3.2.4 POSTMAN (RAW body).................................................................................................... 61 3.2.5 CURL command ............................................................................................................... 62 3.2.6 Troubleshooting Method ................................................................................................ 63 3.3 Game Launch Restrictions ....................................................................................................... 66 3.4 FAQ........................................................................................................................................... 67 4 Game Launch JS Library .................................................................................................................. 68 4.1 Avoid Browser Pop-up Blockers ............................................................................................... 68 4.2 Implementation ....................................................................................................................... 69 5 Integration API................................................................................................................................ 71 5.1 Operator Provided API ............................................................................................................. 71 5.1.1 API Formats ..................................................................................................................... 71 5.1.2 Verify Session .................................................................................................................. 75 5.1.3 Wallet Operation ............................................................................................................. 77 5.2 PG SOFT Provided API .............................................................................................................. 96 5.2.1 API Formats ..................................................................................................................... 96
Pocket Games Software www.pgsoft.com 5.2.2 Bet History Interpreter (Optional)................................................................................... 97 5.2.3 Others (Optional) .......................................................................................................... 101 5.3 Integrate PG SOFT Game into Operator’s iOS Application .................................................... 102 6 Resolve Pending Bet ..................................................................................................................... 103 7 Reset Game State ......................................................................................................................... 105 8 Restrictions ................................................................................................................................... 106 8.1 IP ............................................................................................................................................ 106 8.2 Currency ................................................................................................................................. 106 9 Appendix....................................................................................................................................... 107 9.1 Error Handling ........................................................................................................................ 107 9.1.1 Fail the Request ............................................................................................................. 107 9.2 Error codes ............................................................................................................................. 108 9.3 Currencies .............................................................................................................................. 109 9.4 Currency Base Unit & Handling.............................................................................................. 113 9.5 Bet Types................................................................................................................................ 114 9.6 Transaction Types .................................................................................................................. 115 9.7 Platforms ................................................................................................................................ 115 9.8 Languages .............................................................................................................................. 116
Pocket Games Software www.pgsoft.com Revision History Version Date Description 2.2 2021-05-20 Revamp Version of document 2.3 2021-05-28 5.1.3.2 Bet & Payout Amended Failed Transaction section 2.4 2021-10-13 Added new contents 5.1.1.3 Hash Authentication Added new APIs 5.1.3.2.3 Bet Payout 5.1.3.3 Balance Adjustment Amended restricted countries 8.1 IP Amended currency list 9.2 Currencies Amended contents 5.1.3.2.1 Bet 5.1.3.2.2 Payout Amended Trace Id in API URL and API URL example 5.1.2 Verify Session 5.1.3.1 Get Player Wallet 5.1.3.2.1 Bet 5.1.3.2.2 Payout Added new error code 9.1 Error codes Amended browser support version 2.3 Browser Amended request 3.1.1 URL Scheme Removed section 9.6 Games 2.4.1 2021-11-10 Amended Request 5.1.3.2.3 Bet Payout Change validation description 5.1.3.2.3 Bet Payout Fixed incorrect document layout and format issue 5.1.2 Verify Session 2.4.2 2021-11-24 Amended Request 5.1.3.2.3 Bet Payout Added validation condition 5.1.3.2.3 Bet Payout
Pocket Games Software www.pgsoft.com 2.4.3 2022-06-27 Amended data type 3.1.2 Web Lobby Amended description 3.1.1 URL Scheme 5.1.1.3.1 Header Fields Added new currencies 9.2 Currencies Removed Jackpot related parameters & API 5.2.9 Others (Optional) 5.1.3.2.1 Bet (Deprecated) 5.1.3.2.2 Payout (Deprecated) 5.1.3.2.3 Bet Payout Removed parameter is_minus_count from General Bet Information 5.1.3.2.3 Bet Payout Added missing parameter (create_time & platform) 5.1.3.2.3 Bet Payout Amended description & URL example 5.1.1.3.1 Hash Fields 3.1.2 Web Lobby Removed ct parameter from API request 3.1.1 URL Scheme Added new language 9.6 Languages Amended API URL 5.2.8 Bet History Interpreter (Optional) Removed player related API 5.2.3 Create Player (Optional) 5.2.4 Kick Out Player (Optional) 5.2.5 Suspend Player (Optional) 5.2.6 Resume Player (Optional) 5.2.7 Check Player Status (Optional) Added new API 5.1.3.4 Update Bet Details Added new contents 2.4 Unsupported Browser 2.4.4 2022-07-22 Amended parameter name 3.1.2 Web Lobby 4.2 Implementation Amended contents & removed PHP currency 8.2 Currency Removed DEC & TNT currency 9.2 Currencies Amended contents 3.1.1.1 Reality Check
Pocket Games Software www.pgsoft.com Removed rurl parameter 3.1.1 URL Scheme Amended contents 5.1.1.3.1 Header Fields 2.4.5 2023-05-20 Added new contents and new request parameter 3.1.1 URL Scheme 3.1.2 Web Lobby 5.1.1.3 Hash Authentication (Optional) 5.1.2 Verify Session 5.1.3.2.3 Bet Payout 5.1.3.3 Balance Adjustment 8.1 IP 8.2 Currency Removed Game Authorization Modes 3.1 WebView 3.1.3 WebView (For PG SOFT Apps and PG SOFT Lobby only) 5.2.2 Login Game Removed ESP, HRK, STD, TRL, AUD Currency 9.2 Currencies 2.4.6 2023-09-26 Removed below items 3.1 Game Authorization Modes 3.1.1 URL Scheme 3.1.2 Web Lobby Added new contents and new request parameter 3.1 Game Authorization Mode 3.1.1 HTML Scheme 3.1.1.1 Implementation 3.1.1.2 GetLaunchURLHTML API Amended description 3.1 Game Authorization Modes 3.1.1.3 Reality Check 4.1 Avoid Browser Pop-up Blockers 4.2 Implementation 5.1.2 Verify Session 5.1.3.1 Get Player Wallet 5.1.3.2.1 Bet (Deprecated) 5.1.3.2.2 Payout (Deprecated) 5.1.3.2.3 Bet Payout 5.1.1.3 Hash Authentication 5.1.3.3 Balance Adjustment 2.4.7 2024-02-28 Added new contents 3.1.2 Android SDK Scheme 3.1.3 iOS SDK Scheme 3.1.4 API Reference
Pocket Games Software www.pgsoft.com 3.1.5 Others 9.2 Currencies Amended headings & description 3.1.1.2 GetLaunchURLHTML API 3.1.1.3 Reality Check 3.2 Sample Request 3.3 Game Launch Restrictions 5.1.3.1 Get Player Wallet 5.1.3.2.1 Bet (Deprecated) 5.1.3.2.2 Payout (Deprecated) 5.1.3.2.3 Bet Payout 5.1.3.3 Balance Adjustment Remove description 5.1.1.3 Hash Authentication 2.4.8 2024-03-20 Amended description 3.1.2.1 Implementation 3.1.3.1 Implementation 4.1 Avoid Browser Pop-up Blockers 4.2 Implementation 5.2.2 Bet History Interpreter (Optional) Remove description 9.3 Bet Types 2.4.9 2024-04-02 Amended description 3.1.2.1 Implementation 3.1.3.1 Implementation 8.1 IP 2.4.10 2025-02-21 Amended description and contents 2.2 Hardware 5.1.1.1 Request 5.1.1.2 Response 5.1.1.3 Hash Authentication (Optional) 5.1.3.1 Get Player Wallet 5.1.3.2 Bet & Payout 8.2 Currency 9.1 Error Handling 9.3 Currencies 9.4 Currency Base Unit & Handling Added new contents and new request parameter 3.1.1.2 GetLaunchURLHTML API 5.1.2 Verify Session 5.1.3.2.1 Bet Payout 5.1.3.3 Balance Adjustment 5.2.2 Bet History Interpreter (Optional)
Pocket Games Software www.pgsoft.com Remove currency JPY & GBP 9.3 Currencies Remove parameter iwk 3.1.1.2 GetLaunchURLHTML API Remove Contents Bet (Deprecated) Payout (Deprecated) Add new content 3.1.1.3 Troubleshooting 3.2 Sample Request 3.4 FAQ Remove Hong Kong & United Kingdom 8.1 IP
Pocket Games Software www.pgsoft.com 1 Overview This document details the Integration of the operator’s wallet mode, also known as Seamless Wallet mode. This process details that PG SOFT system will call the operator API in real time for every single transaction while the player is playing games to achieve the addition or deduction of the player's balance.
Pocket Games Software www.pgsoft.com 2 System Requirements 2.1 Game Dimensions PG SOFT games are responsive H5 and are displayed vertically, thus, minimum dimensions are required. Please refer to the following for game dimensions in iframe: Ideal dimensions : 1280 x 720 Minimum dimensions : 540 x 960 Maximum dimensions : 1080 x 2340 2.2 Hardware Android iOS Windows Version of Operating System 5.0 or above 11.0 or above 7 or above RAM 2GB 2GB 2GB CPU ARM Cortex-A9 or above iPhone 7 or above 1 gigahertz (GHz) or faster 32-bit (x86) or 64-bit (x64) processor Dual core at least Storage 2GB and above 2GB and above 20GB and above 2.3 Browser Microsoft Edge : version 79 or above Firefox : version 58 or above Google Chrome : version 59 or above Safari : version 11.1 or above others : browser based on Chromium that equal to Google Chrome 59 or above 2.4 Unsupported Browser Android : Firefox browser, CM browser iOS : CM browser Desktop : UC browser, Baidu browser, Quark browser, CM browser, IE browser
Pocket Games Software www.pgsoft.com 3 Launch Game 3.1 Game Authorization Modes PG SOFT supports one kind of game launch authorization mode: HTML scheme mode is for iOS, Android and browser, it uses the token parameters to authorize and login.
Pocket Games Software www.pgsoft.com 3.1.1 HTML Scheme HTML scheme is the conventional method for launching the game. Players need to log in through the operator’s website and start the game via the game lobby. 1. Players will visit the operator's website and click on the PG SOFT game. 2. The operator's frontend will call the backend service to obtain the HTML code. 3. In response to the frontend's request, the backend service will call the PG SOFT GetLaunchURLHTML API. 4. The PG SOFT API returns the HTML code. 5. The backend will send this HTML code to the frontend. 6. Upon receiving the HTML code, the frontend will execute it, displaying the HTML content on the player's browser (running PG SOFT game). * Note: Please pass the HTTP Header and Body response from Step 4 of PG SOFT directly to the player's browser in Step 5, without any additional processing, to prevent unexpected errors.
Pocket Games Software www.pgsoft.com The Advantage: PG SOFT will return one or more game launch URL based on the request parameters (e.g., client_ip, group_id, etc.). The best game launch URL will be selected for play by detecting on the player's side. In the event of domain name issues, PG SOFT can unilaterally switch the game server address without requiring cooperation from the operator, thus reducing the technical workload on their teams. Why deprecate URL Scheme? 1. In today's complex network landscape, there is currently no service provider in the market capable of perfectly simulating the diverse network conditions experienced by each player. Traditional solutions have proven ineffective in addressing the various network issues encountered by players. 2. To guarantee the optimal gaming experience for every player, PG SOFT is introducing an HTML- based solution. We will test every game launch URL returned from the API, examine it from the player's perspective, ensuring that our testing process remains transparent to operators while alleviating the technical workload on their teams. 3. For the diverse network conditions that may arise at any time across different regions (e.g., domain blocking and domain hijacking, etc.), PG SOFT will continuously fine-tune and optimize our HTML code based on real-world scenarios. 4. To enhance domain security and ensure uninterrupted operations for operators, PG SOFT has also implemented HTML encryption to prevent potential domain blocking and domain hijacking by third parties.
Pocket Games Software www.pgsoft.com 3.1.1.1 Implementation STEP 1 The operator needs to call the PG SOFT GetLaunchURLHTML API through its own backend to obtain the HTML page code. * Note: Operator should include the following (headers) in the API response to prevent the HTML response from being stored in the web browser cache: Cache-Control: no-cache, no-store, must-revalidate Header Parameters: * Note: The following are for reference only and might update accordingly. HTTP Header Remarks Content-Type: text/html HTTP Body format of the response Content-Length HTTP Body length of the response Transfer-Encoding: chunked The server may also use Transfer-Encoding to indicate the length of the returned content. Majority of clients still support this format. Content-Encoding: gzip Gzip compression is used in the HTTP Body of the response Cache-Control: no-cache, no- store, must-revalidate Browser cache control to prevent the browser from caching the HTTP Body of the response Header Examples: 200 OK HTTP/1.1 Content-Type: text/html Content-Encoding: gzip Content-Length: 2910 Cache-Control: no-cache, no-store, must-revalidate Server: nginx/1.24.0 Date: Thu, 16 Nov 2023 07:43:39 GMT
Pocket Games Software www.pgsoft.com STEP 2 After obtaining the HTML page code, execute the HTML code through a web browser. Please refer to the following operator's lobby as an example: <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.4/jquery.min.js"> </script> <script> $(document).ready(function(){ $("button").click(function(){ $.post( "https://<Operator backend service>/api", { param1: "value1", param2: "value2" }, function(data) { var newPage = window.open('', '_blank'); newPage.document.open(); newPage.document.write(data);//Execute HTML Code newPage.document.close(); }); }); }); </script> </head> <body><button>Launch Game</button></body> </html>
Pocket Games Software www.pgsoft.com 3.1.1.2 GetLaunchURLHTML API The operator needs to call the PG SOFT GetLaunchURLHTML API through its own backend to obtain the HTML page code. Request API URL : {PgSoftAPIDomain}/external-game-launcher/api/v1/GetLaunchURLHTML HTTP method : POST URL Parameters: Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format Body Parameters: Parameter name Data Type Mandatory Description operator_token varchar(20) Yes Unique identity of operator path varchar(500) Yes Game path: /<GameID>/index.html Web Lobby path: /web- lobby/{panel_type}/ Tournament path: /tournament/ Bet History Interpreter path: /history/redirect.html Note: Please encode the value with UrlEncode to avoid unexpected errors GameID is the Unique identity for each game 1 panel_type Display panel of web lobby at first load [NO VALUE] : Default Panel (Tournament) tournament/open : Tournament – Open for entry panel tournament/process: Tournament – In progress panel 1 Please get the latest list from PG SOFT
Pocket Games Software www.pgsoft.com tournament/end : Tournament – Ended panel games : Show only game extra_args Query String Parameter Yes Launch game and bet history interpreter parameter (Please refer to relevant parameter list) Note: Please encode the value with UrlEncode to avoid unexpected errors Maximum 500 characters url_type varchar(50) Yes URL Type: game-entry: Game entry web-lobby : Game web lobby entry web-tournament: Tournament entry web-history: Bet history interpreter client_ip varchar(50) Yes Player IP group_id UInt16 No Operator group ID extra_args Parameters (Game Launch) : Parameter name Data Type Mandatory Description btt UInt8 Yes Game launch mode 2 ops varchar(200) Yes Token generated by operator system Note: Please encode the value with UrlEncode to avoid unexpected errors Max 200 characters Please set the parameter value as GUID format or any random string l varchar(50) No Display language of game 3 Default: en te UInt16 No Time elapsed for game health reminder in seconds for operator (Reality check 4 ) 2 Please refer to Bet Types section for complete list 3 Please refer to Languages section for complete list 4 Please refer to Reality Check section for more information
Pocket Games Software www.pgsoft.com ri UInt16 No Reminder interval for game health reminder in seconds (Reality check 4 ) op String No Custom parameter for operator, PG SOFT API will include parameter value upon verifying operator’s player session Note: Please encode the value with UrlEncode to avoid unexpected errors f String No Game exit URL Default: Redirects to PG SOFT quit page Note: Please encode the value with UrlEncode to avoid unexpected errors Assign value to PGGameCloseUrl to close the game window oc Integer No Screen orientation check 5 when launching the game 0: Skip screen orientation check 1: Normal mode (Default) extra_args Parameters (Web Lobby) Parameter name Data Type Mandatory Description ops varchar(200) Yes Token generated by operator system Note: Please encode the value with UrlEncode to avoid unexpected errors Max 200 characters Please set the parameter value as GUID format or any random string l varchar(50) No Display language 6 of web lobby Default: en width Integer No Page width of web lobby Default: Responsive Value range: Value ≥ 930 5 Please refer to screenshot 6 Please refer to Languages section for complete list
Pocket Games Software www.pgsoft.com extra_args Parameters (Tournament) Parameter name Data Type Mandatory Description ops varchar(200) Yes Token generated by operator system Note: Please encode the value with UrlEncode to avoid unexpected errors Max 200 characters Please set the parameter value as GUID format or any random string l varchar(50) No Display language of game 7 Default: en extra_args Parameters (Bet history interpreter 7 ) Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format t String Yes Operator session psid String Yes Parent Bet ID sid String Yes Bet ID gid String No Game ID lang String No Language: en (default) zh type String Yes Fixed value: operator Example: Body: operator_token=xxxx&path=%2F1%2Findex.html&extra_args=btt%3D1%26ops%3D12345-abcd- 1234-abcd-12345&url_type=game-entry&client_ip=1.1.1.1 7 Please refer to Bet History Interpreter section for complete information
Pocket Games Software www.pgsoft.com Response HTTP Body response: The browser only needs to execute the HTML page to launch the game. * Note: The HTML code is subject to adjustment and optimization, and does not follow a fixed format. Please avoid using deserialization or parsing methods to retrieve the final game launch URL. HTTP status code response: Status Code Description Reason Solution 200 Successful response - - 400 Invalid Parameters The format of the parameter is not provided as requested Check whether the HTTP Method, HTTP Header, and HTTP Body are requested accordingly to the requirements. 404 Path not found Invalid path Check whether the path is correct. 500 Server Internal Error An internal server error occurred Retry Inform PG SOFT 504 Gateway Timeout The request has failed to reach the destination server successfully and a proxy server failed. Retry Inform PG SOFT Example for HTML Response (For reference only): <!doctype html><html lang="en">...</html>
Pocket Games Software www.pgsoft.com Screenshot Device compatibility check Screen orientation
Pocket Games Software www.pgsoft.com 3.1.1.3 Troubleshooting The following scenarios may prevent players from successfully accessing the game: Domain name resolution failure (e.g., due to hijacking, blocking, or other interferences) PG SOFT network issues Player-side network failure Outdated system version (may cause SSL certificate verification to fail) Browser restrictions on JavaScript execution Browser settings preventing image downloads Browser restrictions on redirection Ad-blocking plugins installed in the browser Use of a non-mainstream or outdated browser
Pocket Games Software www.pgsoft.com 3.1.1.4 Reality Check In HTML scheme 8 , operator may include “te” and “ri” parameter into the launch game URL for reality check. te : Time used in the calculation for the first reality check in second(s) ri : Reality check interval in second(s) Example: ri=300&te=290 The first reality check reminder will show after 10 seconds (300s-290s=10s), and subsequent reminders will show up for every 5 minutes. Screenshot Health reminder 8 Please refer to HTML Scheme section for more information
Pocket Games Software www.pgsoft.com Screenshot Web Lobby
Pocket Games Software www.pgsoft.com 3.1.2 Android SDK Scheme 3.1.2.1 Implementation STEP 1: Preconfigured 1. Get the SDK AAR file from PG SOFT. 2. Call the API 9 to get a JSON response. Note: Staging SDK file: https://app.pg-staging.com/game-sdk-android/game-sdk.zip * Note: Production SDK file please request from PG SOFT support. * Note: Operator should include the following (headers) in the API response to prevent the HTML response from being stored in the web browser cache: Cache-Control: no-cache, no-store, must-revalidate Header Parameters: * Note: The following are for reference only and might update accordingly. HTTP Header Remarks Content-Type: text/json HTTP Body format of the response Content-Length HTTP Body length of the response Transfer-Encoding: chunked The server may also use Transfer-Encoding to indicate the length of the returned content. Majority of clients still support this format. Content-Encoding: gzip Gzip compression is used in the HTTP Body of the response Cache-Control: no-cache, no- store, must-revalidate Browser cache control to prevent the browser from caching the HTTP Body of the response Header Examples: 9 Please refer to GetLaunchURLSDK API section for more information 200 OK HTTP/1.1 Content-Type: application/json Content-Length: 2910 Cache-Control: no-cache, no-store, must-revalidate Server: nginx/1.24.0 Date: Thu, 16 Nov 2023 07:43:39 GMT
Pocket Games Software www.pgsoft.com STEP 2: Import SDK and dependencies 1. Import dnsjava dependency. 2. Import the SDK Android AAR file into the project: 3. (Recommended) Android builder.gradle minSdk is set to at least 26. STEP 3: Apply the Android SDK Launch game through GameWebViewFragmentActivity The SDK provides GameWebViewFragmentActivity to allow users to launch games quickly. 1. Call the API 10 to get a JSON response and build an SDK webview configuration through GameWebViewConfigModel.Builder. 2. Use GameWebViewConfigModel.Builder to build a DNS configuration for the SDK. 3. Pass the DNS and GameWebView configuration to GameWebViewFragmentActivity through intent.putExtra(<GameWebViewFragmentActivity.KEY>,Bundle) to launch the game: Custom GameWebViewFragmentActivity To load GameWebView through FragmentManager in FragmentActivity, please refer the following code: * Note: GameWebViewFragment needs to be committed in the callback after the onCreate life cycle. 10 Please refer to GetLaunchURLSDK API section for more information // build.gradle dependencies { implementation files("libs/pg-gamesdk-release.aar") implementation group: 'dnsjava', name: 'dnsjava', version: '3.5.2' ... } // Main Activity // data return from API String response = "{"error":null,"data":...}" Intent intent = new Intent(MainActivity.this, GameWebViewFragmentActivity.class); Bundle gameWebViewConfigBundle = new GameWebViewConfigModel.Builder() .sdkResponse(responseData) .locale(GameSDKLocale.ZH) .toBundle(); intent.putExtra(GameWebViewFragmentActivity.GAME_WEB_VIEW_CONFIG_BUNDLE, gameWebViewConfigBundle); Bundle dnsConfigBundle = DNSConfigInstance.GOOGLE_DNS_SERVER.getBundle(); intent.putExtra(GameWebViewFragmentActivity.DNS_CONFIG_BUNDLE, dnsConfigBundle); getApplicationContext().startActivity(intent);
Pocket Games Software www.pgsoft.com // CustomFragmentActivity / CustomAppCompatActivity @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.demo_fragment_activity); } @Override protected void onStart() { GameWebViewFragment webViewFragment = new GameWebViewFragment(DNSConfigInstance.GOOGLE_DNS_SERVER, GameSDKLocale.ZH); getSupportFragmentManager().beginTransaction() .add(R.id.demo_fragment_container, webViewFragment, GameWebViewFragment.class.getName()) .commitNow(); // data return from API String response = "{"error":null,"data":...}" webViewFragment.loadGame(response); } // remove GameWebViewFramgment and clean up private void removeView() { getSupportFragmentManager().beginTransaction().remove(webViewFragment).comm itNow(); webViewFragment = null; } // demo_fragment_activity.xml <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android" android:id="@+id/demo_fragment_container" android:layout_width="match_parent" android:layout_height="match_parent"> </androidx.constraintlayout.widget.ConstraintLayout>
Pocket Games Software www.pgsoft.com Custom DNS The SDK provides four DNS servers by default to resolve domains: If you want to use other custom DNS servers, you can use DNSConfigModel.Builder to create the DNS configuration required by the SDK. If you wish to understand more about DNS resolution and DoH (DNS over HTTPS), please refer the following link: What is DNS CloudFlare public DNS address Apply CloudFlare DNS over HTTPS The IP and DoH domain must be different values. Only PG SOFT internal products’ domains will be resolved into IP by DoH, other domains such as google.com will be resolved by public DNS. DNSConfigInstance.GOOGLE_DNS_SERVER; DNSConfigInstance.CLOUDFLARE_DNS_SERVER; DNSConfigInstance.TENCENT_DNS_SERVER; DNSConfigInstance.ALI_DNS_SERVER; DNSConfigModel customDnsModel = new DNSConfigModel.Builder() .ip("1.1.1.1") .domain("https://1.0.0.1/dns-query") .headerMap(new HashMap<String, String>() {{ put("Accept", "application/dns-json"); }}).build(); GameWebViewFragment webViewFragment = new GameWebViewFragment(customDnsModel); ...
Pocket Games Software www.pgsoft.com SDK exception callback GameWebViewFragment provides setOnErrorReceive to get GameWebView exceptions, VPN configuration exceptions or GameSDKResponseModel exceptions. GameSDKJsonResponseException is thrown by GameSDKResponseModel. This exception is usually thrown when the response data content is incorrect. GameSDKSetupError is thrown by GameWebView or GameVPNService. This exception is usually thrown when DNSConfigModel or GameWebViewConfigModel pass invalid or wrong values. GameSDKCommonError is thrown by GameWebViewFragment or GameVPNService. This exception is usually thrown when data verification passed with incorrect data, such as invalid DNS Server, Game URL. SDK localization Since there is no unified standard for application localization and Locale settings before Android 13. GameSDK provides GameSDKLocale to allow developers to set the language used in GameWebView. The SDK provides language codes (en, zh) in accordance with ISO 639-1 and is packaged using GameSDKLocale. GameSDKLocale language code table can be found here. Please refer to the Locale static variable provided in GameSDKLocale for the list of languages currently provided by the SDK. webViewFragment.setOnErrorReceive(new GameWebViewErrorNotify() { @Override public void onErrorReceive(Exception e) { if (e instanceof GameSDKJsonResponseException) { e.printStackTrace(); } else { throw new RuntimeException(e); } } }); // if language code not support, it will return GameSDKLocale.EN by default. GameSDKLocale locale = GameSDKLocale.getGameSDKLocale("en"); new GameWebViewConfigModel.Builder() .sdkResponse(responseData) .locale(locale) .build(); // or direct set while new GameWebViewFragment GameWebViewFragment webViewFragment = new GameWebViewFragment(DNSConfigInstance.GOOGLE_DNS_SERVER, GameSDKLocale.EN);
Pocket Games Software www.pgsoft.com 3.1.2.2 GetLaunchURLSDK API The operator needs to call the PG SOFT GetLaunchURLSDK API through its own backend to obtain the encrypted redirection address data in JSON format. Request API URL : {PgSoftAPIDomain}/external-game-launcher/api/v2/GetLaunchURLSDK HTTP Method : POST URL Parameters Parameter Name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format Body Parameters Parameter Name Data Type Mandatory Description operator_token varchar(20) Yes Unique identity of operator path varchar(500) Yes Game path: /<GameID>/index.html Web Lobby path: /web- lobby/{panel_type}/ Tournament path: /tournament/ Note: Please encode the value with UrlEncode to avoid unexpected errors GameID is the Unique identity for each game 11 panel_type Display panel of web lobby at first load [NO VALUE] : Default Panel (Tournament) tournament/open : Tournament – Open for entry panel 11 Please get the latest list from PG SOFT
Pocket Games Software www.pgsoft.com tournament/process: Tournament – In progress panel tournament/end : Tournament – Ended panel games : Show only game extra_args Query String Parameter Yes Launch game parameter (Please refer to relevant parameter list) Note: Please encode the value with UrlEncode to avoid unexpected errors Maximum 500 characters url_type varchar(50) Yes URL Type: game-entry: Game entry web-lobby : Game web lobby entry web-tournament: Tournament entry client_ip varchar(50) Yes Player IP group_id UInt16 No Operator group ID extra_args Parameters (Game Launch) Parameter Name Data Type Mandatory Description btt UInt8 Yes Game launch mode 12 ops varchar(200) Yes Token generated by operator system Note: Please encode the value with UrlEncode to avoid unexpected errors Max 200 characters Please set the parameter value as GUID format or any random string l varchar(50) No Display language of game 13 Default: en te UInt16 No Time elapsed for game health reminder in seconds for operator (Reality check 14 ) ri UInt16 No Reminder interval for game health reminder in seconds (Reality check 14 ) 12 Please refer to Bet Types section for complete list 13 Please refer to Languages section for complete list 14 Please refer to Reality Check section for more information
Pocket Games Software www.pgsoft.com op varchar(200) No Custom parameter for operator, PG SOFT API will include parameter value upon verifying operator’s player session Note: Please encode the value with UrlEncode to avoid unexpected errors f varchar(200) No Game exit URL Default: Redirect to PG SOFT quit page Note: Please encode the value with UrlEncode to avoid unexpected errors Assign value to PGGameCloseUrl to close the game window oc UInt8 No Screen orientation check when launching the game 0: Skip screen orientation check 1: Normal mode (Default) extra_args Parameters (Web Lobby) Parameter name Data Type Mandatory Description ops varchar(200) Yes Token generated by operator system Note: Please encode the value with UrlEncode to avoid unexpected errors Max 200 characters Please set the parameter value as GUID format or any random string l varchar(50) No Display language 15 of web lobby Default: en width Integer No Page width of web lobby Default: Responsive Value range: Value ≥ 930 extra_args Parameters (Tournament) Parameter name Data Type Mandatory Description ops varchar(200) Yes Token generated by operator system Note: 15 Please refer to Languages section for complete list
Pocket Games Software www.pgsoft.com Please encode the value with UrlEncode to avoid unexpected errors Max 200 characters Please set the parameter value as GUID format or any random string l varchar(50) No Display language 16 of web lobby Default: en Example: Body: operator_token=xxxx&path=%2F1%2Findex.html&extra_args=btt%3D1%26ops%3D12345-abcd- 1234-abcd-12345&url_type=game-entry&client_ip=1.1.1.1 Response HTTP Body response: Response will be JSON data. * Note: The JSON response format is for reference only and might be updated accordingly. Successful response: Parameter Name Data Type Description error object Returns error message when an error has occurred. Value will be null if no error occurs. data string Obfuscated output content. version string The current version is 2 and may change with future upgrades. Failed response: Parameter Name Data Type Description code int This is an error code. The error code is consistent with the HTTP status code. • 400: Request parameter error • 500: Internal Server Error message string Detailed description of the error tid string Trace ID is an Unique identity (GUID) of the request. Add ?trace_id=xxx in the query string to return the content of the trace id. Note: Please set the parameter value as GUID format 16 Please refer to Languages section for complete list
Pocket Games Software www.pgsoft.com HTTP status code response: Status Code Description Reason Solution 200 Successful JSON Body response - Note: You need to check the error field in the JSON content. If there is a value in this field, an error has occurred. 504 Gateway Timeout The request failed to reach the destination server successfully and a proxy server failed. Retry Inform PG SOFT Example for JSON Response (For reference only): Successful response: Failed response: { "error": null, "version": "2", "data": "CAkQxzAD0odEi0OFisAR1kpRxwAHBkAZUZcMl0NGV8BEQJFDxZxChwyXAICHwAd..." } { "error": { "code": 400, "message": "Request validate error:\n\n\n\tclient_ip parse fail: 2400:9800:1f1:4039:1:0:3866", "tid": "xxx9988" } }
Pocket Games Software www.pgsoft.com 3.1.3 iOS SDK Scheme
Pocket Games Software www.pgsoft.com 3.1.3.1 Implementation STEP 1: Prerequisites 1. Register an Apple account as a member of the Apple Developer Program. 2. Install the latest version of Xcode (15.0.1) 3. Obtain PG SDK XCFramework from PG SOFT Note: Staging SDK file: https://app.pg-staging.com/game-sdk-ios/game-sdk.zip * Note: Production SDK file please request from PG SOFT support. STEP 2: PG SDK integration steps Add a Network Extension Add a “Network Extension” target (Application Extension) 1. Click the "+" button to add the Application Extension's "Network Extension" to your iOS project:
Pocket Games Software www.pgsoft.com 2. Enter the “Product Name” in the pop-up window (for example: XXX-Tunnel) and select the “Packet Tunnel” option in the “Provider Type” drop-down option:
Pocket Games Software www.pgsoft.com 3. Please note that the “Bundle Identifier” of the Application Extension will be used later:
Pocket Games Software www.pgsoft.com 4. Add the “Network Extensions” capability to the “Application Extension” created in the previous step, and choose “Packet Tunnel” in the “Network Extensions” section:
Pocket Games Software www.pgsoft.com 5. Check the framework configuration in the "Build Phases" tab of the "Application Extension":
Pocket Games Software www.pgsoft.com Add “Network Extensions” functionality to the main target 1. Select your primary "target" and go to the "Signing & Capabilities" tab. Click the "+ Capability" button to add the "Network Extensions" capability:
Pocket Games Software www.pgsoft.com 2. Choose the "Packet Tunnel" capability under the "Network Extensions" section:
Pocket Games Software www.pgsoft.com Add framework to "target" Add "NetworkExtension.framework" to the main target
Pocket Games Software www.pgsoft.com Add "PGSDK[x.x.x].xcframework" to the main target
Pocket Games Software www.pgsoft.com Check the framework configuration in the “Build Phases” tab of the main target
Pocket Games Software www.pgsoft.com Integrate PacketTunnelProvider of PGSDK in Application Extension 1. Open "PacketTunnelProvider.swift" (PacketTunnelProvider.h and PacketTunnelProvider.m in the Objective-C version) in "Application Extension" 2. Import "PGSDK" and add the following code to the "startTunnel" function: Swift: PGVPNSettingsManager().setup()
Pocket Games Software www.pgsoft.com Objective-C: PGVPNSettingsManager *manager = [[PGVPNSettingsManager alloc] init]; [manager setup];
Pocket Games Software www.pgsoft.com 3. Configure "NSExtensionPrincipalClass" in "info.plist" in "Application Extension": PGSDK.PGPacketTunnelProvider
Pocket Games Software www.pgsoft.com Integrate PGGameWebView of PGSDK in ViewController 1. Open “ViewController.swift” in the main target (ViewController.h and ViewController.m in the Objective-C version) 2. Import "WebKit" and "PGSDK" into "ViewController" and add a variable of type "PGGameWebView": Swift:
Pocket Games Software www.pgsoft.com Objective-C: 3. Initialize “PGGameWebView” in the “viewDidLoad” function. Please pass the value of section 2.1.1-3 (Bundle Identifier) to the "providerBundleIdentifier" parameter: Please refer API Reference 17 for "dnsType". Swift: 17 Please refer to API Reference section for more information self.webView = PGGameWebView(frame: self.view.bounds, configuration: WKWebViewConfiguration(), providerBundleIdentifier: "", // The value of section 2.3.2.1.1-3 dnsType: PGDNSConfigType.google) if let parentView = self.webView.superview { self.webView.frame = parentView.safeAreaLayoutGuide.layoutFrame } self.view.addSubview(self.webView)
Pocket Games Software www.pgsoft.com Objective-C: 4. Call the "GetLaunchURLSDK" API 18 and load the response. Please call the "load" function of the PGGameWebView instance and pass the API response as a string: Swift: Objective-C: 18 Please refer to GetLaunchURLSDK API section for more information self.webView = [[PGGameWebView alloc] initWithFrame:self.view.bounds configuration:[WKWebViewConfiguration new] providerBundleIdentifier:@"" // The value of section 2.3.2.1.1-3 dnsType:PGDNSConfigTypeGoogle]; UIView *parentView = self.webView.superview; if (parentView) { self.webView.frame = parentView.safeAreaLayoutGuide.layoutFrame; } [self.view addSubview:self.webView]; let apiResp = "" // Response of GetLaunchURLSDK API self.webView.load(apiResp) NSString *apiResp = @""; // Response of GetLaunchURLSDK API [self.webView load:apiResp];
Pocket Games Software www.pgsoft.com 5. The complete code of "ViewController" for your reference. Swift: import UIKit import WebKit import PGSDK class ViewController: UIViewController { var webView: PGGameWebView! override func viewDidLoad() { super.viewDidLoad() // Do any additional setup after loading the view. self.webView = PGGameWebView(frame: self.view.bounds, configuration: WKWebViewConfiguration(), providerBundleIdentifier: "", // The value of section 2.3.2.1.1-3 dnsType: PGDNSConfigType.google) if let parentView = self.webView.superview { self.webView.frame = parentView.safeAreaLayoutGuide.layoutFrame } self.view.addSubview(self.webView) let apiResp = "" // Response of GetLaunchURLSDK API self.webView.load(apiResp) } }
Pocket Games Software www.pgsoft.com Objective-C: #import <UIKit/UIKit.h> #import <WebKit/WebKit.h> #import <PGSDK/PGSDK.h> @interface ViewController : UIViewController @property (nonatomic, strong) PGGameWebView *webView; @end #import "ViewController.h" @interface ViewController () @end @implementation ViewController - (void)viewDidLoad { [super viewDidLoad]; // Do any additional setup after loading the view. self.webView = [[PGGameWebView alloc] initWithFrame:self.view.bounds configuration:[WKWebViewConfiguration new] providerBundleIdentifier:@"" // The value of section 2.3.2.1.1-3 dnsType:PGDNSConfigTypeGoogle]; UIView *parentView = self.webView.superview; if (parentView) { self.webView.frame = parentView.safeAreaLayoutGuide.layoutFrame; } [self.view addSubview:self.webView]; NSString *apiResp = @""; // Response of GetLaunchURLSDK API [self.webView load:apiResp]; } @end
Pocket Games Software www.pgsoft.com 3.1.4 API Reference 3.1.4.1 Implementation PGDNSConfig PGDNSConfigType PGSDKDevToolKit /** * Initialize a PGDNSConfig instance * * PGSDK provides custom DNS functionality, passing necessary parameters to create PGDNSConfig instance * * @param {String} dnsName - DNS name (e.g. Google, Cloudflare) * @param {String} serverURL - DNS over HTTPS resolver URL * @param {String} apiURL - DNS over HTTPS JSON API URL * @param {[String]?} servers - Optional, DNS server IP (IPv4 or IPv6) * @returns {PGDNSConfig} PGDNSConfig instance */ init(dnsName: String, serverURL: String, apiURL: String, servers: [String]?) /** * Enumeration type of DNS Type * * PGSDK provides 4 preconfigured DNS configuration (Google, Cloudflare, Tencent, Alibaba). You can also use a "custom" type, in which case you need to initialize a PGDNSConfig instance yourself */ enum PGDNSConfigType { case google case cloudflare case tencent case ali case custom } /** * Get PGSDK version string */ static func getVersionString() -> String?
Pocket Games Software www.pgsoft.com PGGameWebView /** * Initialize a PGGameWebView instance * * Initialize the PGGameWebView instance and use the preconfigured DNS configuration * * @param {CGRect} frame - Foundation CGRect * @param {WKWebViewConfiguration} configuration - WebKit WKWebViewConfiguration * @param {String} providerBundleIdentifier - Application Extension Bundle Identifier * @param {PGDNSConfigType} dnsType - Enumeration PGDNSConfigType * @returns {PGGameWebView} PGGameWebView instance */ init(frame: CGRect, configuration: WKWebViewConfiguration, providerBundleIdentifier: String, dnsType: PGSDK.PGDNSConfigType) /** * Initialize a PGGameWebView instance * * Initialize the PGGameWebView instance and use custom DNS configuration * * @param {CGRect} frame - Foundation CGRect * @param {WKWebViewConfiguration} configuration - WebKit WKWebViewConfiguration * @param {String} providerBundleIdentifier - Application Extension Bundle Identifier * @param {PGDNSConfig} dnsConfig - PGDNSConfig instance * @returns {PGGameWebView} PGGameWebView instance */ init(frame: CGRect, configuration: WKWebViewConfiguration, providerBundleIdentifier: String, dnsConfig: PGSDK.PGDNSConfig) /** * Load the game based on the "GetLaunchURLSDK" API response * * After initializing the PGGameWebView instance and getting the response of the "GetLaunchURLSDK" API, pass the response as a string to the "load" function of the PGGameWebView instance to load the game * * @param {String} responseString - API response */ func load(_ responseString: String)
Pocket Games Software www.pgsoft.com PGVPNSettingsManager 3.1.5 Others 1. The minimum iOS version supported by PGSDK is 14.0. 2. Since this project involves the "Network Extension" framework, the iOS simulator does not support it, please run/debug on a physical device. /** * Initialize a PGVPNSettingsManager instance */ init() /** * Perform necessary settings */ func setup()
Pocket Games Software www.pgsoft.com 3.2 Sample Request 3.2.1 HTML Direct Launch Game Mode Below is an example of HTML code for operator front-end. Player will launch PG SOFT games by clicking the launch game link. 1. Players will visit the operator's website and click on the PG SOFT game. The operator's frontend will call the backend service to obtain the HTML code. 2. In response to the frontend's request, the backend service will call the PG SOFT GetLaunchURLHTML API. 3. PG SOFT GetLaunchURLHTML API returns the HTML code. 4. The operator's backend API will pass the HTTP headers and HTML code from PG SOFT to the operator's frontend (which is the new window opened in STEP 1) without any modifications. 5. Upon receiving the HTML code, the frontend will execute it, displaying the HTML content on the player's browser (which is running the PG SOFT game). <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> </head> <body><a href="https://<Operator Backend API>/pg-game-launcher-html- mode.php?param1=xxx&param2=yyy" target="_blank">Launch Game</a></body> </html>
Pocket Games Software www.pgsoft.com 3.2.2 iFrame Mode (Recommended) Note: Integrating iFrame mode helps effectively protect PG SOFT’s domain. This integration method is recommended in regions where hijacking or domain blocking is common. 1. Players will visit the operator's website and click on the PG SOFT game. The operator's frontend will call the backend service to obtain the HTML code. 2. In response to the frontend's request, the backend service will call the PG SOFT GetLaunchURLHTML API. 3. PG SOFT GetLaunchURLHTML API returns the HTML code. 4. The operator's backend API will pass the HTTP headers and HTML code from PG SOFT to the operator's frontend (which is the new window opened in STEP 1) without any modifications. 5. Upon receiving the HTML code, the frontend will execute it, displaying the HTML content on the player's browser (which is running the PG SOFT game). Note: To ensure PG SOFT games launch properly, the allow attribute must be included in the iframe. <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head></head> <body> <iframe allow="web-share *; clipboard-write *; screen-wake-lock *; fullscreen *" src="https://<Operator Backend API>/pg-game-launcher-html- mode.php?param1=xxx&param2=yyy"> </iframe> </body> </html>
Pocket Games Software www.pgsoft.com The reason is as follows: Clipboard-write: When players experience network issues in the game launcher, they can click the Copy button and provide the copied information to PG SOFT Support. This helps PG SOFT identify and resolve the issue more efficiently.
Pocket Games Software www.pgsoft.com In the PG Verification, if a player is unable to open the PG SOFT verification page directly, they can still copy the URL and perform the verification manually. Fullscreen and screen-wake-lock: Required by game engine.
Pocket Games Software www.pgsoft.com 3.2.3 Ajax Mode (Not Recommended) * Note: Ajax mode is not recommended due to the following potential issues: Scenario 1: In iOS Safari, a "Pop-ups blocked" prompt may appear, preventing the game window from opening. Users must tap "Always Show" and then tap "Open" again to proceed. (This corresponds to Method 1 in the sample code below.) The browser's Back button will not return the user to the page they were on before launching the PG SOFT game. (This corresponds to Method 2 in the sample code below.) Examples: 1. Players will click the ‘Launch Game’ button. The operator’s backend API will be triggered via Ajax. 2. Operator’s backend API will send a request to PG SOFT GetLaunchURLHTML API. 3. PG SOFT GetLaunchURLHTML API returns the HTML code. 4. The operator's backend API will pass the HTTP headers and HTML code from PG SOFT to the operator's frontend (which is the new window opened in STEP 1) without any modifications. 5. Upon receiving the response from the operator’s backend API, Ajax will execute the callback function, displaying the HTML content on the player's browser (which is running the PG SOFT game). <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.4/jquery.min.js"></script > <script> $(document).ready(function(){ $("button").click(function(){ $.getJSON("https://httpbin.org/anything", { html: '<h1>New Window</h1><p>Hello World!</p>' }, function(data) { var html = data.args.html; // Method 1, use new window to execute HTML var newWindow = window.open('', '_blank'); newWindow.document.open(); newWindow.document.write(html); newWindow.document.close(); // Method 2, use existing window to execute HTML. document.write(html); }); }); }); </script> </head> <body><button>Launch Game</button></body> </html>
Pocket Games Software www.pgsoft.com 3.2.4 POSTMAN (RAW body) The example below demonstrates how to call the PG SOFT GetLaunchURLHTML API using Postman to retrieve the HTML code. Request: Headers: Content-Type: application/x-www-form-urlencoded Body (raw): operator_token=xxxx&path=%2F1%2Findex.html&extra_args=btt%3D1%26ops%3D12345-abcd- 1234-abcd-12345&url_type=game-entry&client_ip=1.1.1.1
Pocket Games Software www.pgsoft.com 3.2.5 CURL command The example below demonstrates how to call the PG SOFT GetLaunchURLHTML API using a CURL command to retrieve the HTML code. Request: curl -v -X POST "https://api.pg-bo.me/external-game- launcher/api/v1/GetLaunchURLHTML" -H "Content-Type: application/x-www-form-urlencoded" -d "operator_token=xxxx&path=%2F1%2Findex.html&extra_args=btt%3D1%26ops%3D12345- abcd-1234-abcd-12345&url_type=game-entry&client_ip=1.1.1.1"
Pocket Games Software www.pgsoft.com 3.2.6 Troubleshooting Method 1. Copy the request information. Example as below:
Pocket Games Software www.pgsoft.com 2. If the browser does not allow copying, the collapsed content will automatically expand. In that case, please provide a screenshot instead like below:
Pocket Games Software www.pgsoft.com 3. To speed up troubleshooting, please provide a screenshot of each link under the Test tab:
Pocket Games Software www.pgsoft.com 3.3 Game Launch Restrictions Multiple windows or multiple game launches are unsupported by PG SOFT games. Players will be locked and kick out of games, and encounter errors when the below are detected: S1302XXXXXXXX: Unsuccessful Game Authorization S1309XXXXXXXX: Player account been suspended S1305XXXXXXXX: Server request failure When encountering the above errors, players may close the game windows and relaunch the game to unlock their player accounts: S1302XXXXXXXX: Please relaunch the game S1309XXXXXXXX: Player account will be unlocked automatically after 10 minutes, please relaunch the game after 10 minutes S1305XXXXXXXX: Please relaunch the game
Pocket Games Software www.pgsoft.com 3.4 FAQ 1. 403 Error when calling the game-launcher API Access to the game-launcher API requires API whitelisting. Please contact PG SOFT Support for API whitelisting. 2. DNS error, network error, or connection timeout Please check the player's network settings. 3. HTTP Error 400/404 Please check the Content-Type of the request. 4. HTTP Error 500 Please retry the request. If the issue persists, contact PG SOFT for further support. 5. Invalid characters appearing on the page: a. Ensure Gzip compression is enabled in the browser. b. Check if the operator’s server is passing the Content-Encoding HTTP header correctly. 6. Browser-side scripting errors For supported browser types and versions, please contact PG SOFT Support.
Pocket Games Software www.pgsoft.com 4 Game Launch JS Library Operator is required to launch the game by using PG SOFT JS library to provide the best gaming experience to players: Implementation of automatically adapting pop-up window according to the user's display size. PG SOFT games are all designed to be displayed vertically, the pop-up window format is consistent with product design. Achieving the optimal gaming Interface height will allow users to feel visually comfortable, in line with usage habits. Presenting the best in-game visual quality to the players, providing the best gaming experience. 4.1 Avoid Browser Pop-up Blockers The general rules that popup blockers will engage are: Invoked from JavaScript that is not invoked by direct user action. Pop-up content are not from the same domain as the source. Operator is recommended to follow the instructions below to avoid browser pop-up blockers: Create a frontend page and call their own backend service ( 19 HTML Scheme ). When players click the game launch button/link, use the PG SOFT JS function (PGSDK.launchGame) and launch the operator frontend page. 19 Please refer to HTML Scheme section for more information
Pocket Games Software www.pgsoft.com 4.2 Implementation Step 1 Include the following line in the HTML <head> tags: Note: Operator can self-host the JS library as well: https://public.pg-staging.com/sdk/main.min.js Step 2 Operator is required to create a self-host frontend page to call their own backend service (HTML Scheme 20 ) in order to obtain the HTML code for launching the game. Sample code of operator’s frontend page: 20 Please refer to HTML Scheme section for more information <script defer src="https://public.pg-staging.com/sdk/main.min.js"></script> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.4/jquery.min.js"> </script> <script> $(document).ready(function(){ $.post( "https://<Operator backend service>/api", { param1: "value1", param2: "value2" }, function(data) { window.document.write(data);//Execute HTML Code }); }); </script> </head> </html>
Pocket Games Software www.pgsoft.com Step 3 Use the following JS script to launch PG SOFT games. Parameters: Parameter name Data Type Mandatory Description operator_frontend_URL String Yes Operator self-host frontend page in Step 2, which will call their own backend service Example: PGSDK.launchGame('https://[OperatorDomain]/operator-frontend.html'); PGSDK.launchGame('{operator_frontend_URL}');
Pocket Games Software www.pgsoft.com 5 Integration API 5.1 Operator Provided API 5.1.1 API Formats 5.1.1.1 Request The API uses HTTP form methods and a RESTful endpoint structure. PG SOFT will send requests in the following content type: Content-Type: application/x-www-form-urlencoded 5.1.1.2 Response API returns JSON-formatted responses. For successful and failed API request, operator is required to return an API response with HTTP status code 200. The API response should be returned within 10 seconds to prevent the request being treated as a timeout request. API uses global JSON response format for all API methods, with the following content type: Content-Type: application/json Parameters: Parameter name Data Type Description data 21 JSON Object Response information for API methods error JSON Object Error information when an error or exception occur Example: Successful Response { "data": { [API method response. JSON object format may vary depending on API methods] }, "error": null, } Failed/Error Response { "data": null, "error": { "code": "[Error code]", "message": "[Error message]" } } 21 This field will show null value in error response
Pocket Games Software www.pgsoft.com 5.1.1.3 Hash Authentication (Optional) We highly recommend that the operator integrate hash authentication to secure every request. If the operator chooses to integrate with hash authentication, PG SOFT system will validate the hash information provided in the header fields for every request. Note: Hash Authentication is disabled by default. Please request with PG SOFT if operator wishes to integrate Hash Authentication. The operator shall perform encryption and calculations based on the received request parameters and the body parameters should not be hardcoded. 5.1.1.3.1 Header Fields The following table describes the various request headers in the preceding example: Component Description Host API domain Example: apiexample.pgsoft.com x-date Current date (UTC) in YYYYMMDD format Example: 20190902 x-content- sha256 SHA256 hash of the request string body Example: 1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3 069143ed46f1 Authorization Combination of various components for requesting authentication Example: PWS-HMAC-SHA256 Credential=20190902/OPERATORTOKENEXAMPLE/pws/v1,Signe dHeaders=host;x-content-sha256;x- date,Signature=d78220cf06ae85f9d1db11dad9c3fd92679961 9eab3d28574aadb8cf328cd7aa
Pocket Games Software www.pgsoft.com Example Host: apiexample.pgsoft.com x-date: 20190902 x-content-sha256: 1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1 Authorization: PWS-HMAC-SHA256 Credential=20190902/OPERATORTOKENEXAMPLE/pws/v1,SignedHeaders=host;x -content-sha256;x- date,Signature=d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aadb 8cf328cd7aa Header: x-content-sha256 Calculate a SHA256 hash of the request string body: Example POST body: operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&count=5000&bet_ type=1&row_version=1346592723000 x-content-sha256: 1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1
Pocket Games Software www.pgsoft.com Header: Authentication The following table describes the various components of the Authorization header value in the preceding example: To calculate a signature, you first need a string that includes {host}{x-content-sha256}{x- date} to sign. You will then calculate a HMAC-SHA256 hash of the string to sign by using a signing key: Calculate a HMAC-SHA256 hash of the string body: Example Salt : SALTEXAMPLE Host : apiexample.pgsoft.com x-date : 20190902 x-content-sha256 : 1700116101f424b9f6fc695b4dbaf2b7b0ee763ba1b3b53298e3069143ed46f1 Signature: d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aadb8cf328cd7aa Component Description Credential Your access key ID and the scope information, which includes the date, operator token, and service that were used to calculate the signature. This string has the following form: {x-date}/{operator_token}/pws/v1 Example: 20190902/OPERATORTOKENEXAMPLE/pws/v1 SignedHeaders A semicolon-separated list of request headers that you will use to compute the Signature. The list includes header names only, and the header names must be in lowercase. Fixed Value: host;x-content-sha256;x-date Signature The 256-bit signature is expressed as 64 lowercase hexadecimal characters. Example: d78220cf06ae85f9d1db11dad9c3fd926799619eab3d28574aa db8cf328cd7aa hmac-sha256({salt}, {host}{x-content-sha256}{x-date})
Pocket Games Software www.pgsoft.com 5.1.2 Verify Session PG SOFT game system will call this operator API to check the player session token generated when players login to game. Note: This API is required for 22 HTML Scheme authorization mode New player will be created automatically Request API URL : {OperatorAPIDomain}/VerifySession HTTP method : POST URL Parameters: Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format Body Parameters: Parameter name Data Type Mandatory Description operator_token String Yes Unique identity of operator secret_key String Yes Shared passphrase between PG SOFT and operator operator_player_session String Yes Token generated by operator’s system when the game is launched ( 23 HTML Scheme ) game_id Integer No Unique identity of games ip String No Player IP address custom_parameter String No operator_param values in HTML Scheme extra_args parameter. bet_type Integer Yes Game launch mode 24 Example: URL: https://operator.api/VerifySession?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311 Body: operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&operator_player_session=a2b3c 4d5e6f7g8&game_id=1&ip=1.1.1.1&custom_parameter=operatorparam123&bet_type=1 22 Please refer to HTML Scheme section for login flow and details 23 Please refer to HTML Scheme section for more information 24 Please refer to Bet Types section for complete list
Pocket Games Software www.pgsoft.com Validation Operator is required to perform validations to the following parameters: Parameter name Description Expected behaviour operator_token Make sure the parameter value is the same as the one PG SOFT has provided. Return error when not match secret_key operator_player_session Make sure the operator_player_session matches with the token generated in 25 HTML Scheme Response Body Parameters: JSON Object Parameter name Data type Mandatory Description player_name String Yes Unique identity of players player name is not case sensitive Only alphabet, number, and “@”, “-”, ”_” symbols are allowed Note: Max 50 characters nickname String No Nickname of player Note: Max 50 characters currency String Yes Currency of player Example: { "data": { "player_name": "player1", "nickname":"nickname", "currency": "CNY" }, "error": null } Error Response Code Message 1034 Invalid request 1200 Internal server error 25 Please refer to HTML Scheme section for more information
Pocket Games Software www.pgsoft.com 5.1.3 Wallet Operation 5.1.3.1 Get Player Wallet Operators are required to provide the total balance of all the wallets that can be used in PG SOFT games. This includes the total balance in the cash wallet. Request API URL : {OperatorAPIDomain}/Cash/Get HTTP method : POST URL Parameters: Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: This ID is for issue troubleshooting only. Please do not use this ID for duplicate request validation. Body Parameters: Parameter name Data Type Mandatory Description operator_token String Yes Unique identity of operator secret_key String Yes Shared passphrase between PG SOFT and operator player_name String Yes Unique identity of players operator_player_session String No Token generated by operator’s system when the game is launched ( 26 HTML Scheme ) game_id Integer No Unique identity of games Example: URL: https://operator.api/Cash/Get?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311 Body: operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&operato r_player_session=a2b3c4d5e6f7g8&game_id=1 26 Please refer to HTML Scheme section for more information
Pocket Games Software www.pgsoft.com Validation Operators are required to perform validation to the following parameters: Parameter name Description Expected behaviour operator_token Make sure the parameter value is the same as the one PG SOFT has provided. Return error when not match secret_key player_name Make sure the parameter value matches the given player’s name in Verify Session 27 Response Body Parameters: JSON Object Parameter name Data type Mandatory Description currency_code String Yes Currency of player balance_amount Decimal Yes Cash Balance of player Note: Amount must be >= 0 Supports up to 2 decimal places Extra decimal values will be truncated. Example: The game will show 11.12 if balance_amount value is 11.125 Balance amounts do not included free game and bonus balances. Operator should always return the latest player balance. updated_time Long Yes Updated time of player record (Unix time stamp in milliseconds) Example: { "data": { "currency_code": "CNY", "balance_amount": 11.12, "updated_time": 1530879795000 }, "error": null } 27 Please refer to Verify Session section for more information
Pocket Games Software www.pgsoft.com Error Response Code Message 1034 Request is not valid 3005 Player wallet does not exist
Pocket Games Software www.pgsoft.com 5.1.3.2 Bet & Payout PG SOFT system will expect idempotent operations for all API operations. Operators are required to perform duplicate request checks for all incoming transaction requests. PG SOFT may resend a transaction due to network difficulties or other unforeseen circumstances. Please refer to the following precautions and process flow to correctly handle duplicated requests: Operators are required to validate both operator_token and secret_key for every transaction request. transaction_id is the only unique identifier for every transaction request, including bet and payout. In the case where a request with the same transaction_id is received and the previous request has already been processed successfully, please ignore the duplicated request, and return the previous successful response for the duplicated request. In the case where a request with the same transaction_id is received and the previous request has failed, please retry the operation and return the corresponding results to PG SOFT. For requests with a new transaction_id, operators may proceed to wallet addition or deduction accordingly and return the successful response to PG SOFT. Real Transfer Amount To prevent losses caused by incorrect currency base rate conversions, PG SOFT has introduced an update to the Seamless Wallet API. A new parameter real_transfer_amount/realTransferAmount has been added to both the API request and response. The real_transfer_amount parameter represents the actual value of the amount in the request. Operators are required to include this parameter in the request and validate that the realTransferAmount returned in the API response matches the original value. Operators should not update the players’ wallet amount and must return an error response to PG SOFT if any discrepancies are found during validation. Example: If an operator uses a 1:1000 conversion for a currency with a base unit of 1000, and the transfer_amount in the request is 1, then the real_transfer_amount should be 1000. If the operator receives an incorrect real_transfer_amount, they should return an error response and immediately inform PG SOFT.
Pocket Games Software www.pgsoft.com Game Disconnected If a player encounters an error and is disconnected from the game, the PG SOFT system will automatically resume the game from its previous stage (including free spin, bonus, or free game) without displaying any alert on the next player login. Players will see the same screen as before the error occurred and will be able to continue the game from the previous stage. Failed Transaction May refer to 9.1.1 Fail the Request
Pocket Games Software www.pgsoft.com 5.1.3.2.1 Bet Payout This transaction request is the combination of both bet and payout in a single request. The PG SOFT system will call the operator’s API in real time while the player is betting to either the add or deduct the player's balance. Operators are required to respond within 10 seconds or an API timeout will happen. Request API URL : {OperatorAPIDomain}/Cash/TransferInOut HTTP method : POST URL Parameters: Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format Body Parameters: Category Parameter name Data Type Mandatory Description Authentication Information operator_token String Yes Unique identity of operator secret_key String Yes Shared passphrase between PG SOFT and operator operator_player _session String No Token generated by operator system when game is launched ( 28 HTML Scheme ) General Bet Information player_name String Yes Unique identity of players game_id Integer Yes Unique identity of games parent_bet_id String Yes Unique identity of parent bet bet_id String Yes Unique identity of child bet Note: Unique key for bets currency_code String Yes Currency of player bet_amount Decimal Yes Bet amount Note: PG SOFT will send a bet request with ZERO transfer amount for free spins win_amount Decimal Yes Win amount. Note: PG SOFT will send a payout request with ZERO transfer amount for the following: 28 Please refer to HTML Scheme section for more information
Pocket Games Software www.pgsoft.com Every action (Example: split card) performed by players in card games Special features in some slot games transfer_amount Decimal Yes Player Win Loss amount Note: The amount can be positive or negative Negative: Balance deduction Positive: Balance addition real_transfer_amount Decimal Yes [New] Actual value of the transaction amount in the real world Note: The operator is required to validate the value transaction_id String Yes Unique identity of transaction. Format: {BetId}-{ParentBetId}- {transactionType}-{balanceId} Transaction type: 106: BetPayout 400: BonusToCash 403: FreeGameToCash Note: Max 50 characters wallet_type String No To indicate the type of wallet for the current transaction. C: Cash B: Bonus G: FreeGame bet_type Integer Yes Bet types of bet record: 1: Real game platform String No Platform of player 29 create_time Long Yes Bet start time and bet last updated time (Unix time stamp in milliseconds) Note: updated_time is not equal to bet end time updated_time Long Yes 29 Please refer to Platform section for more information
Pocket Games Software www.pgsoft.com Bet Indicator is_validate_bet Boolean No To indicate if the request is a transaction that has been resent for validation True: Resent transaction False: Normal transaction is_adjustment Boolean No To indicate if the request is an adjustment or a normal transaction for a reset game state True: Adjustment False: Normal transaction is_parent_zero_stake Boolean No To indicate if the request is having 0 bet amount for the first bet of the round. True: Having 0 bet amount for the first bet of the round (For Bacarrat Deluxe’s free hands action) False: Having amount larger than 0 in the first bet of the round is_feature Boolean No To indicate the spin type True: Feature spin False: Normal spin is_feature_buy Boolean No To indicate if a player has purchased the game feature Note: Only applicable for games with buy feature, such as feature buy, sure win bet etc is_end_round Boolean No To indicate if the current game hand has ended Free Game Information free_game _transaction_id String No Unique identity of free game. It can only be seen when Free Game has been assigned to the player Note: Only available for free game created using External API free_game_name String No Given name of free game. It can only be seen when Free Game has been assigned to the player free_game_id Integer No Unique identity of free game.
Pocket Games Software www.pgsoft.com It can only be seen when Free Game has been assigned to the player is_minus_count Boolean No To indicate the spin type in free game True: Normal spin (Free game count is deducted) False: Free spin Bonus Game Information bonus_transaction_id String No Unique identity of bonus game. It can only be seen when Bonus Game has been assigned to the player Note: Only available for bonus game created using External API bonus_name String No Given name of bonus game. It can only be seen when Bonus Game has been assigned to the player bonus_id Integer No Unique identity of bonus game. It can only be seen when Bonus Game has been assigned to the player bonus_balance _amount Decimal No Total number of bonus amount in bonus wallet. It can only be seen when the player chooses to complete the bonus with cash. bonus_ratio_amount Decimal No Rollover amount the player needs to achieve in bonus game. It can only be seen when the player chooses to complete the bonus with cash. Example: URL: https://operator.api/Cash/TransferInOut?trace_id=b3f37e57-2873-40b1-aa95-f126c25ed311 Body: operator_token=12345&secret_key=bfvcdb&player_name=player123&operator_player_sessi on=vcbcvbcvb&game_id=1&parent_bet_id=123456&bet_id=123456&bet_type=1&currency_code =IDR&create_time=1530879795000&updated_time=1530879795000&bet_amount=100&win_amoun t=40&transfer_amount=-60&transaction_id=123456-123456-106- 0&wallet_type=C&is_feature=False&is_minus_count=False&real_transfer_amount=-6000
Pocket Games Software www.pgsoft.com Validation Operator is required to perform validation to the following parameters: Parameter name Description Expected behaviour player_name Make sure the parameter value matches the given player information in Verify Session 30 Return error when not match currency_code operator_token Make sure the parameter value is the same as the one PG SOFT has provided. secret_key operator_player_session Make sure the operator_player_session matches the token generated in HTML Scheme 31 Do not validate operator_player_session when is_validate_bet or is_adjustment parameter value is true Note: PG SOFT system may resend request for validation or pending bet Return successful response even with outdated operator_player_session bet_amount Make sure there is an error response when there is insufficient balance (bet_amount) Return error response 3202 transfer_amount Make sure there is an error response when there is insufficient balance (negative transfer_amount) Make sure player balance after transaction (amount with 2 decimal places) is correct Return successful response with the correct cash balance Make sure zero transfer amount is accepted for parent bet Note: PG SOFT system will send a request with ZERO transfer amount for Bacarrat Deluxe’s free hands action Make sure zero transfer amount is accepted for child bet Note: PG SOFT system will send a request with ZERO transfer amount for free spin Make sure there is an error response when win_amount – bet_amount != transfer_amount Return error response 3073 real_transfer_amount [New] Ensure an error response is triggered when an incorrect parameter value is detected. Return error response 3107 30 Please refer to Verify Session section for more information 31 Please refer to HTML Scheme section for more information
Pocket Games Software www.pgsoft.com Please return an error if any of the following conditions are not met: For 1:1 base unit currency: real_transfer_amount = transfer_amount For 1:1000 base unit currency and conversion handle by PG SOFT: real_transfer_amount = transfer_amount For 1:1000 base unit currency and conversion handle by operator (Default): real_transfer_amount = transfer_amount * 1000 transaction_id Ignore wallet operation for duplicated requests (Requests with the same transaction_id) Return successful response with the correct cash balance parent_bet_id Proceed wallet operation for request with the same game hand (Requests with the same parent_bet_id but different bet_id) bet_id
Pocket Games Software www.pgsoft.com Response Body Parameters: JSON Object Parameter name Data type Mandatory Description currency_code String Yes Currency of player balance_amount Decimal Yes Cash Balance of player Note: Amount must be >= 0 Support up to 2 decimal places Extra decimal values will be truncated. Example: Game will show 11.12 if balance_amount value is 11.125 updated_time Long Yes Updated time of transaction (Unix time stamp in milliseconds) Note: Response updated_time must be the same as the requested updated_time for transaction reference real_transfer_amount Decimal Yes [New] Actual value of the transaction amount in the real world Note: The operator is required to validate the value Example: { "data": { "currency_code": "IDR", "balance_amount": 11.12, "updated_time": 1530879795000 "real_transfer_amount": -60000 }, "error": null }
Pocket Games Software www.pgsoft.com Error Response Code Message 3004 Player does not exist 3005 Player wallet does not exist 3021 Bet does not exist 3033 Bet failed 3107 Invalid configuration 3202 Insufficient player balance Important Note: Operators SHOULD NOT fail the requests for free spin or respin transactions. Please refer to 9.1.1 Fail the Request for more information.
Pocket Games Software www.pgsoft.com 5.1.3.3 Balance Adjustment PG SOFT will use this API to add or deduct a player’s balance. This API may be used for certain events, such as Cash Tournaments. Request API URL : {OperatorAPIDomain}/Cash/Adjustment HTTP method : POST Body parameters: Category Parameter name Data Type Mandatory Description Authentication Information operator_token String Yes Unique identity of operator secret_key String Yes Shared passphrase between PG SOFT and operator General Information player_name String Yes Unique identity of players currency_code String Yes Currency of player transfer_amount Decimal Yes Adjustment Amount Negative amount: Balance deduction Positive amount: Balance addition real_transfer_amount Decimal Yes [New] Actual value of the transaction amount in the real world Note: The operator is required to validate the value adjustment_id String (100) Yes Reference ID for Adjustment adjustment_transaction_id String (100) Yes Unique identity of transaction Format: {adjustment_id}- {transaction_type} Note: Max 200 characters Operator should use this parameter to check if the request is duplicated
Pocket Games Software www.pgsoft.com and implement idempotent operation adjustment_time Long Yes Adjustment time (Unix time stamp in milliseconds) transaction_type String Yes Adjustment source: 115: Money Rain Cash Reward (Promotion) 900: External Adjustment 901: Tournament Reward 902: Treasure Portal Cash Reward (Promotion) bet_type Integer Yes Game launch mode 32 promotion_id Integer No Reference ID for Promotion promotion_type Integer No Promotion Type: 1: Money Rain 2: Money Rain Daily Bonus 3: Daily Cashpot 4: Treasure Portal remark String No Remark for Balance Adjustment Example operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&player_name=player123&bet_typ e=1&currency_code=CNY&transfer_amount=100.00&real_transfer_amount=100.00&adjustmen t_time=1530879795000&adjustment_id=ABC1530879&adjustment_transaction_id=ABC1530879 -900&transaction_type=900 Validation Operator is required to perform validation to the following parameters: Parameter name Description Expected behaviour player_name Make sure the parameter value matches the given player information in Verify Session 33 Return error when not match currency_code operator_token Make sure the parameter value is the same as the one PG SOFT has provided. secret_key transfer_amount Make sure there is an error response when there is insufficient balance (negative transfer_amount) Return error response 3202 Make sure player balance after adjustment (amount with 2 decimal places) is correct Return successful Make sure 0 or negative amount is accepted 32 Please refer Bet Types for more info 33 Please refer to Verify Session section for more information
Pocket Games Software www.pgsoft.com Make sure the adjustment performs correctly and accordingly Negative: Balance deduction Positive: Balance addition response with correct balance adjustment_transaction_id Ignore wallet operation for duplicated requests (Request with same transaction_id) real_transfer_amount [New] Ensure an error response is triggered when an incorrect parameter value is detected. Please return an error if any of the following conditions are not met: For 1:1 base unit currency: real_transfer_amount = transfer_amount For 1:1000 base unit currency and conversion handle by PG SOFT: real_transfer_amount = transfer_amount For 1:1000 base unit currency and conversion handle by operator (Default): real_transfer_amount = transfer_amount * 1000 Return error response 3107 Response Body Parameters: JSON Object Parameter name Data type Mandatory Description adjust_amount Decimal Yes Adjusted Amount Note This amount is for reference purpose. PG SOFT will not validate it. Response adjust_amount must be the same as the requested transfer_amount for transaction reference balance_before Decimal Yes Player balance before adjustment (balance_before) & Player balance after adjustment (balance_after) Note Amount must be >= 0 Only support up to 2 decimals balance_after Decimal Yes
Pocket Games Software www.pgsoft.com Extra decimal values will be truncated. Example: Game will show 11.12 if balance_amount value is 11.125 updated_time Long Yes Updated time of transaction (Unix time stamp in milliseconds) Note: Response updated_time must be the same as the requested adjustment_time for transaction reference real_transfer_amount Decimal Yes [New] Actual value of the transaction amount in the real world Note: The operator is required to validate the value Example { "data": { "adjust_amount": 100.00, "balance_before": 0.00, "balance_after": 100.00, "updated_time": 1737941479768 "real_transfer_amount": 100.00 }, "error": null } Error Response Code Message 3004 Player does not exist 3005 Player wallet does not exist
Pocket Games Software www.pgsoft.com 5.1.3.4 Update Bet Details PG SOFT game system will call this operator API to update the operator’s latest bet end time when the bet is successful in PG SOFT system. Request API URL : {OperatorAPIDomain}/Cash/UpdateBetDetail HTTP method : POST Body Parameters: Parameter name Data Type Mandatory Description operator_token String Yes Unique identity of operator secret_key String Yes Shared passphrase between PG SOFT and operator bet_details Json Array Yes List of bet ID with bet end time updated_time Long Yes API request time (Unix time stamp in milliseconds) Parameter: bet_details Parameter name Data Type Mandatory Description bet_id String Yes Unique identity of child bet Note: Unique key for bets end_time Long Yes Bet end time (Unix time stamp in milliseconds) Example: operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl&bet_details=[{"bet_id":"1456887894","e nd_time":"1644476958000"},{"bet_id":"1456887895","end_time":"1644476958000"}]&updated_ti me=1645414794000
Pocket Games Software www.pgsoft.com Validation Operator is required to perform validation to the following parameters: Parameter name Description Expected behaviour operator_token Make sure the parameter value is the same as the one PG SOFT has provided. Return error when not match secret_key Response Body Parameters: JSON Object Parameter name Data Type Mandatory Description is_success Boolean Yes To indicate if the request is received True: Received False: Not Received Example: { "data": { "is_success": true }, "error": null }
Pocket Games Software www.pgsoft.com 5.2 PG SOFT Provided API 5.2.1 API Formats 5.2.1.1 Request The API uses HTTP form methods and a RESTful endpoint structure. Operator is required to send requests in the following content type: Content-Type: application/x-www-form-urlencoded 5.2.1.2 Response API returns JSON-formatted responses. For successful and failed API requests, PG SOFT system will return an API response with HTTP status code 200. API uses global JSON response format for all API methods, with the following content type: Content-Type: application/json Parameters: Parameter name Data Type Description data 34 JSON Object Response information for API methods error 35 JSON Object Error information when an error or exception occur 34 This field will show null value in error response 35 This field will show null value in successful API response. Please refer to Error Handling 1.1.1 Fail the Request Operators should always practice idempotent responses to prevent duplicate modifications to player balances. If one of the errors below has already been returned in a previous response, operators are required to return the same error response again to ensure the request status remains synchronized between the operator and PG SOFT. The following error codes will cause PG SOFT games to stop and display an error during bet transactions. The bet request will be cancelled when any of the following error codes are returned: 3004 PlayerNotFoundException 3005 WalletNotFoundException 3008 BonusNotFoundException 3009 FreeGameNotFoundException 3019 NotEnoughFreeGameException 3021 BetNotFoundException 3030 FreeGameAlreadyExpiredException 3035 InvalidFreeGameMultiplierException 3042 BonusLockedException
Pocket Games Software www.pgsoft.com Example: Successful Response { "data": { [API method response. JSON object format may vary depending on API methods] }, "error": null, } Failed/Error Response { "data": null, "error": { "code": "[Error code]", "message": "[Error message]" } } 3043 FreeGameLockedException 3055 SnapshotNotFoundException 3057 InvalidFreeGameCoinSizeException 3059 BetLimitExceededException 3062 TransactionRolledBackException 3065 BonusAlreadyExpiredException 3073 BetFailedException 3094 MaximumBetLimitReachErrorCode 3095 BalanceDecreaseLimitReachErrorCode 3103 PromotionTransactionNotFoundException 3200 NotEnoughBalanceException 3201 NotEnoughBonusBalanceException 3202 NotEnoughCashBalanceException 3250 – 3259 reserved error codes However, the above error codes should only be used for bet or transfer-out requests. Operators SHOULD NOT return these error codes under the following conditions, as doing so may cause incorrect game behaviour and results, leading to operator losses or significant player winnings: Payout request Feature spin / free spins / Respins (when parameter is is_feature = true) Error codes section for error response format
Pocket Games Software www.pgsoft.com 5.2.2 Bet History Interpreter (Optional) To reveal a player’s bet results and details for specific bet. Step 1 Before getting the bet detail, operator is required to call this API to get operator's session (Session timeout: 30 minutes). Request API URL : {PgSoftAPIDomain}/Login/v1/LoginProxy HTTP method : POST URL Parameters: Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format Body Parameters: Parameter name Data Type Mandatory Description operator_token String Yes Unique identity of operator secret_key String Yes Shared passphrase between PG SOFT and operator Example: URL: https://api.pg-bo.me/external/Login/v1/LoginProxy?trace_id=b3f37e57-2873-40b1- aa95-f126c25ed311 Body: operator_token=abc123&secret_key=a1b25cde5f3gh46ijkl
Pocket Games Software www.pgsoft.com Response Body Parameters: JSON Object Parameter name Data Type Description operator_session String Operator session Example: { "data": { "operator_session": E4ECB5CF-0BC6-4DA8-8551-8526F48AB9CD }, "error": null } Step 2 Get bet detail by: API URL : {PgSoftAPIDomain}/external-game-launcher/api/v1/GetLaunchURLHTML HTTP method : POST URL Parameters: Body Parameters: Parameter name Data Type Mandatory Description path varchar (500) Yes /history/redirect/html extra_args Query String Paramater Yes Bet history interpreter parameter (Please refer to relevant parameter list) Note: Please encode the value with UrlEncode to avoid unexpected errors Maximum 500 characters url_type varchar (50) Yes URL Type: web-history: Bet History interpreter client_ip varchar (50) Yes Player IP group_id UInt16 No Operator group ID Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format
Pocket Games Software www.pgsoft.com extra_args Parameters Parameter name Data Type Mandatory Description trace_id String Yes Unique identity (GUID) of the request Note: Please set the parameter value as GUID format t String Yes Operator session psid String Yes Parent Bet ID sid String Yes Bet ID gid String No Game ID lang String No Language: en (default) zh type String Yes Fixed value: operator Example: Body: path%3D%2Fhistory%2Fredirect.html%26extra_args%3Dtrace_id%3Dde335d4d-b133-4422- 9c6e-8554cb1fbc7e%26t%3DE4ECB5CF-0BC6-4DA8-8551- 8526F48AB9CD%26psid%3D1821471534863220736%26sid%3D1821471534863220736%26lang%3Den% 26type%3Doperator%26url_type%3Dweb-history%26client_ip%3D1.1.1.1 Response HTTP Body response: The browser only needs to execute the HTML page to launch the game. * Note: The HTML code is subject to adjustment and optimization, and does not follow a fixed format. Please avoid using deserialization or parsing methods to retrieve the final game launch URL. HTTP status code response: Status Code Description Reason Solution 200 Successful response - - 400 Invalid Parameters The format of the parameter is not provided as requested Check whether the HTTP Method, HTTP Header, and HTTP Body are requested accordingly to the requirements. 404 Path not found Invalid path Check whether the path is correct. 500 Server Internal Error An internal server error occurred Retry Inform PG SOFT 504 Gateway Timeout The request has failed to reach the destination server successfully and a proxy server failed. Retry Inform PG SOFT
Pocket Games Software www.pgsoft.com Example for HTML Response (For reference only): <!doctype html><html lang="en">...</html>
Pocket Games Software www.pgsoft.com 5.2.3 Others (Optional) PG SOFT provides several APIs for different modules that are optional for integration. Operator may choose to integrate based on their requirements: Bet History : To get a player’s bet history. Game List : To get the latest game list and available bet sizes. Free Game : To perform several actions (For example: Create free game, assign player into free game, cancel free game, etc.) through API. Bonus Game : To perform several actions (For example: Create bonus game, assign player into bonus game, cancel bonus game, etc.) through API. Tournament : To get tournament list, add player into tournament and get tournament ranking through API.
Pocket Games Software www.pgsoft.com 5.3 Integrate PG SOFT Game into Operator’s iOS Application Operator’s application needs to meet the following requirements to launch PG SOFT games in the application client: iOS 8.0 or above WKWebView PG SOFT game will prompt a “Poor Visit Experience” message if it does not meet the minimum requirements. Players are allowed to continue launching the game but it may not guarantee a stable, and high performance experience of the PG SOFT game. To ensure the application client passes the PG SOFT game requirement check, operator is required to include the following codes when initializing WKWebView component in application: This is to construct a WKUserContentController object and set its userContentController property on the configuration. Please take note that the userContentController must have at least one scriptMessageHandler (assign through addScriptMessageHandler) For more details regarding WKWebView, please refer to Apple Developer Documentation WKUserContentController *controller = [[WKUserContentController alloc] init]; [controller addScriptMessageHandler: self name: @"Could be any srting value"]; WKWebViewConfiguration *configuration = [[WKWebViewConfiguration alloc] init]; configuration.userContentController = controller; WKWebView *webView = [[WKWebView alloc] initWithFrame: CGRectZero configuration: configuration]; webView.uiDelegate = self;
Pocket Games Software www.pgsoft.com 6 Resolve Pending Bet Sometimes pending bets may occur due to unforeseen circumstances during gameplay due to network latency, system failure, system timeout and so on. Generally, pending bet will be resolved automatically when the player relaunches the game. However, the bet will remain in pending status for some rare scenarios: Player did not relaunch the game after encountering an error. PG SOFT system did not receive any response from the operator when resolving pending bets. PG SOFT system received an error response from the operator when resolving pending bets. Default interval of pending bet resolving time is set to 60 minutes. Pending bets which exceed the interval will be resolved by PG SOFT system automatically. This interval is customizable, and every operator can have their own bet resolve interval time. Manual resolve is required when pending bets cannot be resolved after several attempts. In such cases, the operator is required to resolve the pending bet manually, and PG SOFT will mark these bets statuses as complete after getting the confirmation from the operator.
Pocket Games Software www.pgsoft.com Screenshot Player Pending Bet Resolve Flow
Pocket Games Software www.pgsoft.com 7 Reset Game State All games will support the resume feature which allows returning players to continue the game at their last game state from any device. For example, players will be able to continue a game with a bonus game state few days after even if the player had closed the game when the player won the bonus game. However, the player’s game state will reset every 90 days by default. This interval is customizable, and every operator can have their own game state reset interval time. System will clear all finished and unfinished game progress, and the player will not be able to continue a game after it has been reset. For transfer wallet mode, every player game state will reset every 90 days by default: PG SOFT system will reset a player’s game state automatically if there are no pending bets for the player. Screenshot Player’s Game State Reset Flow for Transfer Wallet
Pocket Games Software www.pgsoft.com 8 Restrictions 8.1 IP Players from the following restriction area are not able to access PG SOFT game: Malaysia Singapore Taiwan United States of America Macau Israel Iran North Korea Australia United Arab Emirates United Kingdom 8.2 Currency Please find the following for the currencies not supported by PG SOFT: AUD ESP HRK STD TRL HKD GBP JYP (Not accepted for new requests) MOP MYR SGD TWD All cryptocurrencies except MBTC, UBTC, USDT, TUSD & USDC
Pocket Games Software www.pgsoft.com 9 Appendix 9.1 Error Handling 9.1.1 Fail the Request Operators should always practice idempotent responses to prevent duplicate modifications to player balances. If one of the errors below has already been returned in a previous response, operators are required to return the same error response again to ensure the request status remains synchronized between the operator and PG SOFT. The following error codes will cause PG SOFT games to stop and display an error during bet transactions. The bet request will be cancelled when any of the following error codes are returned: 3004 PlayerNotFoundException 3005 WalletNotFoundException 3008 BonusNotFoundException 3009 FreeGameNotFoundException 3019 NotEnoughFreeGameException 3021 BetNotFoundException 3030 FreeGameAlreadyExpiredException 3035 InvalidFreeGameMultiplierException 3042 BonusLockedException 3043 FreeGameLockedException 3055 SnapshotNotFoundException 3057 InvalidFreeGameCoinSizeException 3059 BetLimitExceededException 3062 TransactionRolledBackException 3065 BonusAlreadyExpiredException 3073 BetFailedException 3094 MaximumBetLimitReachErrorCode 3095 BalanceDecreaseLimitReachErrorCode 3103 PromotionTransactionNotFoundException 3200 NotEnoughBalanceException 3201 NotEnoughBonusBalanceException 3202 NotEnoughCashBalanceException 3250 – 3259 reserved error codes However, the above error codes should only be used for bet or transfer-out requests. Operators SHOULD NOT return these error codes under the following conditions, as doing so may cause incorrect game behaviour and results, leading to operator losses or significant player winnings: Payout request Feature spin / free spins / Respins (when parameter is is_feature = true)
Pocket Games Software www.pgsoft.com 9.2 Error codes Error code Description 1034 Request is not valid 1035 Operation Failed 1200 Internal server error 1204 Failed to get operator 1300 Invalid player session 1301 Player session token is empty 1302 Invalid player session 1303 Server error occurs 1305 Invalid player – Player does not exist: [player name] 1306 Player is blocked to access current game 1307 Invalid player session 1308 Player session is expired 1309 Player is inactive 1310 Failed to verify operator player session 1315 Player’s operation in progress 1400 Game is under maintenance 1401 Game is inactive 1402 Game does not exist 3001 Value cannot be null 3004 Player does not exist 3005 Player wallet does not exist 3006 Player wallet already exists 3009 Free game does not exist 3013 Service Exception: Not enough balance to transfer 3014 Free game cannot be cancelled 3019 Not enough free game 3021 No bet exists 3022 Bet already pay-out 3030 Free game expired 3031 Free game already converted 3032 Bet already existed 3033 Bet failed 3034 Pay-out failed 3035 Invalid multiplier 3036 Not enough balance to convert 3040 Transaction does not exist 3202 Not enough cash balance to bet
Pocket Games Software www.pgsoft.com 9.3 Currencies Currency Code Currency Symbol Currency Name Base Unit AED د. إDirham des Émirats arabes unis 1 AFN ؋Afghanistan Afghani 1 ALL L Albanian Lek 1 AMD ֏ Armenian Dram 1 ANG ƒ Netherlands Antilles Guilder 1 AOA Kz Angola Kwanza 1 ARS $ Argentine Peso 1 AWG ƒ Aruba Guilder 1 AZN Azerbaijani Manat 1 BAM KM Bosnian Convertible Marka 1 BBD $ Barbados Dollar 1 BDT Tk Taka bangladais 1 BGN лв Lev bulgare 1 BHD BD Bahrain Dinar 1 BIF FBu Burundian Franc 1000 BMD $ Bermuda Dollar 1 BND B$ Brunei Dollar 1 BOB $b Bolíviano bolivien 1 BRL R$ Brazil Real 1 BSD $ Bahamian Dollar 1 BTN Nu. Bhutanese Ngultrum 1 BWP P Botswana Pula 1 BYN BYN Belarusian Rouble 1 BYR Br Belarusian Ruble 1 BZD BZ$ Belize Dollar 1 CAD C$ Canadian Dollar 1 CDF FC Congolese Franc 1000 CHF Fr. Swiss Franc 1 CLP $ Chilean Peso 1 CNY ¥ Chinese Yuan 1 COP $ Colombian Peso 1000 CRC Colon costaricain 1 CSD din Serbian Dinar 1 CUP Cuba Peso 1 CVE $ Cape Verde Escudo 1
Pocket Games Software www.pgsoft.com CZK Czech Koruna 1 DJF Fdj Djiboutian Franc 1 DKK kr. Danish Krone 1 DOP RD$ Peso dominicain 1 DZD DA Dinar algérien 1 EGP £ Livre égyptienne 1 ERN Nkf Eritrea Nakfa 1 ETB ብር Ethiopian Birr 1 EUR Euro 1 FJD $ Fiji Dollar 1 FKP £ Falkland Islands (Malvinas) Pound 1 GEL Georgian Lari 1 GHS GH¢ Ghanaian Cedi 1 GIP £ Gibraltar Pound 1 GMD D Gambian Dalasi 1 GNF FG Guinean Franc 1000 GTQ Q Quetzal guatémaltèque 1 GYD $ Guyana Dollar 1 HNL L Honduran Lempira 1 HTG G Haiti Gourde 1 HUF Ft Hungarian Forint 1 IDR Rp Indonesian Rupiah 1000 ILS Shekel israélien 1 INR Indian Rupee 1 IQD د. عDinar irakien 1000 IRR Iranian Rial 1000 ISK kr Couronne islandaise 1 JMD J$ Jamaica Dollar 1 JOD د. أJordanian Dinar 1 KES KSh Kenyan Shilling 1 KGS KGS Som du Kirghizistan 1 KHR Cambodian Riel 1000 KMF CF Comorian Franc 1 KPW North Korea Won 1 KRW South Korean Won 1000 KWD كKuwait Dinar 1 KYD $ Cayman Islands Dollar 1 KZT Kazakhstani Tenge 1 LAK Lao Kip 1000 LBP ل. لLivre libanaise 1000
Pocket Games Software www.pgsoft.com LKR Roupie sri lankaise 1 LRD $ Liberia Dollar 1 LSL L Lesotho Loti 1 LVL Ls Latvian Lats 1 LYD LD Dinar libyen 1 MAD DH Moroccan Dirham 1 MBTC Milli Bitcoin 1 MDL L Moldovan Leu 1 MGA Ar Madagascar Ariary 1000 MKD ден Dinar macédonien 1 MMK K Burmese Kyat 1000 MNT Mongolian Tughrik 1000 MUR Mauritius Rupee 1 MVR Rf. Maldivian Rufiyaa 1 MWK MK Malawian Kwacha 1 MXN $ Mexican Peso 1 MZN MT Mozambican Metical 1 NAD $ Namibia Dollar 1 NGN Nigerian Naira 1 NIO C$ Cordoba nicaraguayen 1 NOK kr Norwegian Krone 1 NPR Nepal Rupee 1 NZD $ New Zealand dollar 1 OMR Oman Rial 1 PAB B/. Balboa panaméen 1 PEN S/ Peruvian Sol 1 PGK K Papua New Guinea Kina 1 PHP Philippine Peso 1 PKR Pakistan Rupee 1 PLN Poland Złoty 1 PYG Gs Guarani paraguayen 1000 QAR QR Rial qatari 1 RON lei Romanian Leu 1 RSD РСД Serbian Dinar 1 RUB Russian Ruble 1 RWF FRw Rwandan Franc 1000 SAR SR Rial saoudien 1 SBD $ Solomon Islands Dollar 1 SCR SR Seychellois Rupee 1 SDG ج. س. Livre soudanaise 1 SEK kr Swedish Krona 1
Pocket Games Software www.pgsoft.com SHP £ Saint Helena Pound 1 SLL Le Sierra Leonean Leone 1000 SOS S Somalia Shilling 1 SRD $ Suriname Dollar 1 SVC $ Colon salvadorien 1 SYP £ Livre syrienne 1 SZL L Swazi Lilangeni 1 THB ฿ Thai Baht 1 TJS TJS Tajikistan Somoni 1 TMT T Turkmenistan Manat 1 TND د. تDinar tunisien 1 TOP T$ Tongan paʻanga 1 TRX TRX TRON Crypto 1 TRY Turkish Lira 1 TTD TT$ Trinidad and Tobago Dollar 1 TUSD TUSD TrueUSD(Crypto) 1 TZS TSh Tanzanian Shilling 1000 UAH Ukrainian Hryvnia 1 UBTC µɃ Micro Bitcoin 1 UGX USh Uganda Shilling 1000 USD $ United States Dollar 1 USDC USDC USD Coin (Crypto) 1 USDT Tether 1 UYU $U Peso uruguayen 1 UZS soʻm Uzbekistani Som 1000 VES Bs.S Venezuelan Bolívar 1 VND Vietnamese Dong 1000 VUV VT Vanuatu Vatu 1 WST $ Samoa Tala 1 XAF FCFA Central African CFA Franc BEAC 1 XCD $ East Caribbean Dollar 1 XOF CFA CFA Franc 1 XPF CFP Franc 1 YER Rial yéménite 1 ZAR R Rand sud-africain 1 ZMW ZK Zambian Kwacha 1 GC GC Stake Gold Coins (Social Casino Currency) 1 SC SC Stake Cash (Social Casino Currency) 1
Pocket Games Software www.pgsoft.com 9.4 Currency Base Unit & Handling Operators should always verify the base unit in the currency list before submitting a request for environment setup. Below is a list of currencies with a base unit of 1000. Operators are required to choose whether the conversion will be handled by PG SOFT or the operator in the integration application. BIF (Burundian Franc) CDF (Congolese Franc) COP (Colombian Peso) GNF (Guinean Franc) IDR (Indonesian Rupiah) IQD (Dinar Iranian) IRR (Iranian Rial) KHR (Cambodian Riel) KRW (South Korean Won) LAK (Lao Kip) LBP (Livre Lebanese) MGA (Madagascar Ariary) MMK (Burmese Kyat) MNT (Mongolian Tughrik) PYG (Guarani Paraguay) RWF (Rwandan Franc) SLL (Sierra Leonean Leone) TZS (Tanzanian Shilling) UGX (Uganda Shilling) UZS (Uzbekistani Som) VND (Vietnamese Dong) Note: Please refer to the appendix for the complete currency list with base units. Always check with PG SOFT if a currency is not listed.
Pocket Games Software www.pgsoft.com The table below explains the relationship between currencies with a base unit of 1000 and how this impacts the API, system, reporting, and settlement processes: API Get TransferIn TransferOut TransferInOut Adjustment External- Grabber Real Amount 1000 Game Display/ PG SOFT BackOffice 1 Settlement 1000 Operator Handle 1:1000 Conversion (Default) PG SOFT Send 1 1 1 Operator Send 1 PG Handle 1:1000 Conversion PG Send 1000 1000 1 Operator Send 1000 9.5 Bet Types Bet Type Game Mode 1 Real game
Pocket Games Software www.pgsoft.com 9.6 Transaction Types Code Transaction type 1 Cash 2 Bonus game 3 Free game 9.7 Platforms Code Category Platform 1 Web Windows 2 macOS 3 Android 4 iOS 5 others 6 Cordova Android 7 iOS 8 Electron Windows 9 macOS 10 Native Windows 11 macOS 12 Android 13 iOS 98 others System 99 Smartbot
Pocket Games Software www.pgsoft.com 9.8 Languages Code Language en English (default) en-stkus Social casino (for currencies SC & GC) ar-EG Arabic az-Latn-AZ Azerbaijani (Latin) bg-BG Bulgarian bn-BD Bengali cs-CZ Czech da-DK Danish de-DE German el-GR Greek es-ES Spanish et-EE Estonian fa-IR Farsi fi-FI Finnish fr-FR French hi-IN Hindi hu-HU Hungarian hy-AM Armenian id-ID Indonesian it-IT Italian ja-JP Japanese ko-KR Korean lo-LA Lao lt-LT Lithuanian mn-MN Mongolian my-MM Burmese no-NO Norwegian nl-NL Dutch pl-PL Polish pt-PT Portuguese pt-BR Portuguese Brazilian ro-RO Romanian ru-RU Russian sr-Latn-RS Serbian (Latin) si-LK Sinhala sk-SK Slovak sq-AL Albanian
Pocket Games Software www.pgsoft.com sv-SE Swedish th-TH Thai tr-TR Turkish uk-UA Ukrainian ur-PK Urdu uz-Latn-UZ Uzbek (Latin) vi-VN Vietnamese zh Chinese