Android Quick Integration
Follow this guide to integrate the SUDGI SDK and advertising capabilities, complete SDK initialization and user authentication, then launch games by gameId.
1. Import the SDK and Configure the Project
1. Import via Gradle
Configure the Maven repository in the project root build.gradle, and add the dependency in the app-level build.gradle:
def sdk_version = '3.0.0'
dependencies {
implementation "global.sud.gi:SUDGI:${sdk_version}"
// Optional: enable MP3 encoding in the game runtime
// implementation "global.sud.gi:SUDGI-shine:${sdk_version}"
// Choose at least one ad source
implementation "global.sud.gi:SUDM-adapter-admob:${sdk_version}"
implementation "global.sud.gi:SUDM-adapter-carty:${sdk_version}"
implementation "global.sud.gi:SUDM-adapter-topon:${sdk_version}"
implementation "global.sud.gi:SUDM-adapter-max:${sdk_version}"
implementation "global.sud.gi:SUDM-adapter-taku:${sdk_version}"
}SUDGI, shared components, SUDM Core, and its adapters share the sdk_version variable. Change sdk_version and update the entire SDK set together when upgrading.
SUDGI-shine is an optional runtime extension for encoding audio as MP3. SUDGI does not include it automatically. Uncomment the dependency above only when your games need MP3 encoding, and use the same sdk_version as the other SUD components. Omit it when MP3 encoding is not needed.
SUDGI automatically includes the shared components. Keep only the ad sources you use. The selected adapters automatically include the advertising core. AdMob, Carty, TopOn, and MAX include their platform SDKs automatically.
When using Taku, add maven { url 'https://jfrog.takuad.com/artifactory/china_sdk' } to the project's existing Maven repository configuration.
After adding dependencies, continue with “Advertising Integration” and “SDK Initialization” below to configure app IDs, applicable consent flows, and privacy parameters.
2. Third-party Version Requirements
Use the paired versions below as the integration baseline; do not downgrade them. Before upgrading, consult the official version information and confirm compatibility with the SUD components you use.
| Third-party module | Integration baseline | Version information |
|---|---|---|
AdMob: com.google.android.gms:play-services-ads | Fixed at 25.4.0 | Google release notes |
Carty: io.carty.bidad:carty-sdk | Fixed at 1.11.0 | Carty changelog |
TopOn: com.anythink.sdk:core-tpn | Fixed at 6.6.22.3 | TopOn Android integration guide |
MAX: com.applovin:applovin-sdk | Fixed at 13.5.1 | MAX Android integration guide |
Taku: com.anythink.sdk:core-taku | Fixed at 6.6.40 | Taku Android integration guide |
2. Advertising Integration
With the dependencies installed, configure the host app for the selected ad sources and complete the applicable consent flow before SDK initialization.
Host Configuration
AdMob App ID
Required when using AdMob. Add the following inside <application> in the host's AndroidManifest.xml.
<meta-data
android:name="com.google.android.gms.ads.APPLICATION_ID"
android:value="ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY" />Replace the value with the Android app ID from the AdMob console (containing ~), not an ad unit ID (containing /).
The AdMob adapter declares network permissions. Check the Merged Manifest if host merge rules alter those permissions or the app ID; a missing app ID causes initialization to fail. See AdMob Android setup.
Advertising ID
Applies when targeting Android 13 (API 33) or later and using GAID. Check the final Merged Manifest for this permission; add it under <manifest> only if missing.
<uses-permission android:name="com.google.android.gms.permission.AD_ID" />Google Mobile Ads SDK 20.4.0 and later declare this permission. Normal merging does not require a duplicate declaration or a runtime permission request.
Game JavaScript does not need to collect or pass GAID manually. Do not treat missing or all-zero IDs as valid when tracking is limited, the identifier is deleted, or the service is unavailable. See Android 13 advertising ID changes.
User Consent and Authorization
User Consent
The SDK accepts host-confirmed states; it does not determine legal applicability or display consent dialogs. Permissions and privacy parameters do not replace consent handling.
Required when advertising consent must be collected. Complete this integration before SDK initialization.
Reuse the host's CMP or privacy flow. When using Google UMP Android:
- Update consent information on each launch and show required forms.
- Provide a privacy-options entry point when required.
- Check
ConsentInformation.canRequestAds()before requesting ads.
Pass the host's confirmed privacy states into initialization in the next section. Do not map canRequestAds() directly to all four states being granted.
3. SDK Initialization
Complete the advertising dependencies, host configuration, and applicable consent flows above, then initialize the SDK once during app startup with the host-confirmed privacy states.
3.1 Interface Definition
/**
* Initialize the SDK
*
* @param context context
* @param appId appId
* @param appKey appKey
* @param privacyConfig Host-confirmed advertising privacy states
* @param listener Callback listener
*/
public static void initSDK(
Context context,
String appId,
String appKey,
SUDOPPrivacyConfig privacyConfig,
SUDOPInitSDKListener listener
)3.2 Example
See SUDOPPrivacyConfig for fields and enum definitions. Replace the sample app ID, app key, and privacy states; the values below illustrate syntax, not default consent.
SUDOPPrivacyConfig privacyConfig = SUDOPPrivacyConfig.builder()
.setGdprConsentStatus(SUDOPPrivacyConfig.GdprConsentStatus.NOT_APPLICABLE)
.setDoNotSellStatus(SUDOPPrivacyConfig.DoNotSellStatus.NOT_APPLICABLE)
.setLgpdConsentStatus(SUDOPPrivacyConfig.LgpdConsentStatus.NOT_APPLICABLE)
.setAgeRestrictedTreatment(SUDOPPrivacyConfig.AgeRestrictedTreatment.UNSPECIFIED)
.build();
SUDOP.initSDK(
getApplicationContext(),
"Your AppID",
"Your AppKey",
privacyConfig,
new SUDOPInitSDKListener() {
@Override
public void onSuccess() {
Log.d("SUDOP", "SDK initialized successfully");
}
@Override
public void onFailure(int retCode, String retMsg) {
Log.e("SUDOP", "SDK initialization failed: " + retMsg);
}
}
);Parameters
| Parameter | Type | Description |
|---|---|---|
context | Context | Android context; passing ApplicationContext is recommended |
appId | String | AppID assigned by the SUD platform |
appKey | String | AppKey assigned by the SUD platform |
privacyConfig | SUDOPPrivacyConfig | Host-confirmed advertising privacy states |
listener | SUDOPInitSDKListener | Initialization result callback |
See initSDK for the complete initialization API.
4. User Authentication (auth)
Before launching a game, user authentication must be completed. After the business backend generates the userSignature, the client calls SUDOP.auth to synchronize the user's login state.
Before the first authentication, register an authentication invalidation listener. When notified, obtain a fresh signature for the current account and call SUDOP.auth again.
4.1 Interface Definition
/**
* Authenticate user login status
*
* @param userSignature userSignature
*/
public static void auth(
String userSignature,
SUDOPAuthListener listener
)4.2 Example
String userSignature = "Signature string issued by the business backend";
SUDOP.auth(userSignature, new SUDOPAuthListener() {
@Override
public void onSuccess() {
Log.d("SUDOP", "User authentication successful");
}
@Override
public void onFailure(int retCode, String retMsg) {
Log.e("SUDOP", "User authentication failed: " + retMsg);
}
});4.3 Parameters
| Parameter | Type | Description |
|---|---|---|
userSignature | String | User signature generated and issued by the business backend |
listener | SUDOPAuthListener | Authentication result callback |
5. Launch the Game
After completing SDK initialization and user authentication, you can launch a game by gameId.
Usage
String language = "zh-CN";
SUDOPGameTask sudOPGameTask = SUDOP.startGame(gameId, language, new SUDOPStartGameListener() {
@Override
public void onGameViewCreated(View view) {
// Game View created
// Add the view to your own game container
gameContainer.addView(view);
}
@Override
public void onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) {
// Game package decryption callback
// If your business has no custom encrypted-package handling logic, this can usually be left unhandled
}
@Override
public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
// Game runtime environment created
// Here you can set screen orientation, register business callbacks, set game state, etc.
// Example: set screen orientation based on the game's recommended orientation
if ("landscape".equals(gameInfo.deviceOrientation)) {
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE);
} else if ("portrait".equals(gameInfo.deviceOrientation)) {
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT);
} else if ("auto".equals(gameInfo.deviceOrientation)) {
setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR);
}
// Example: register the business delegate
// SUDOP.registerWrappedClient(handle, sudOPWrappedClient);
// Save the game handle for later control of game state or resource release
gameHandle = handle;
}
@Override
public void onSuccess(String gameId, SUDRTGameHandle gameHandle) {
Log.d("SUDOP", "Game launched successfully: " + gameId);
}
@Override
public void onProgress(int progress) {
Log.d("SUDOP", "Game loading progress: " + progress + "%");
}
@Override
public void onFailure(int retCode, String retMsg) {
Log.e("SUDOP", "Game launch failed: " + retCode + ", " + retMsg);
}
});Pass your app's selected BCP 47 language tag, using the same value as getGameInformation.
The existing SUDOP.startGame(gameId, listener) overload remains available. When language is null or empty, the loading view uses the system language. Names and icons first match the language key, then their map's default entry; if the icon is still empty, the loading view uses the legacy game_icon URL. See startGame for language selection and the complete fallback rules.
Once the game is running, mini-games load and display ads through the sud ad APIs; see game developer examples. SDK initialization success does not mean an ad has loaded; game code must wait for the ad object’s onLoad.
6. SUDOPStartGameListener Callbacks
SUDOPStartGameListener is used to receive key states during the game launch process.
| Callback Method | Description |
|---|---|
onGameViewCreated(View view) | The game View has been created. Developers need to add this View to their own page container |
onGamePkgDecrypt(GamePkgDecryptHandle handle, String filePath) | Game package decryption callback. If your business side needs to handle a custom encrypted package, you can perform the decryption logic here; if not, it usually requires no handling |
onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) | The game runtime environment has been created. Here you can save the SUDRTGameHandle, set screen orientation, register the business delegate, set game state, etc. |
onSuccess(String gameId, SUDRTGameHandle gameHandle) | Game launched successfully |
onProgress(int progress) | Game loading progress callback; progress is usually 0 ~ 100 |
onFailure(int retCode, String retMsg) | Game launch failed; you can display a message or retry based on the error code and error message |
7. Set the Game Orientation
After the game is created, the SDK returns game information via SUDOPGameInfo, in which deviceOrientation indicates the game's recommended orientation.
Example:
@Override
public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
if ("landscape".equals(gameInfo.deviceOrientation)) {
activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE);
} else if ("portrait".equals(gameInfo.deviceOrientation)) {
activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT);
} else if ("auto".equals(gameInfo.deviceOrientation)) {
activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR);
}
}deviceOrientation | Description |
|---|---|
landscape | Landscape |
portrait | Portrait |
auto | Auto-rotate following the sensor |
8. Register the Business Delegate
If the game needs to request capabilities from the App, such as user information, image picking, image preview, or saving images, you need to register a business delegate.
Registering it in the onCreated callback is recommended:
@Override
public void onCreated(SUDRTGameHandle handle, SUDOPGameInfo gameInfo) {
SUDOP.registerWrappedClient(handle, sudOPWrappedClient);
}Here, sudOPWrappedClient is the delegate object implemented on the business side.
9. Destruction and Resource Release
When the user exits the game page, for example on Activity.finish(), you need to release game-related resources to avoid memory, audio, and rendering resource leaks.
Example:
@Override
public void finish() {
if (sudOPGameTask != null) {
sudOPGameTask.destroy();
sudOPGameTask = null;
}
super.finish();
}
@Override
protected void onDestroy() {
super.onDestroy();
if (sudOPGameTask != null) {
sudOPGameTask.destroy();
sudOPGameTask = null;
}
}The exact release methods should follow the API provided by your current SDK version. If your business holds a game task object, game handle, or registered listeners, they should all be cleaned up when the page is destroyed.
10. Full Integration Flow
Import the SUDGI SDK, SUDM Core, and ad-source dependencies
↓
Complete advertising host configuration and applicable consent flows
↓
SUDOP.initSDK with privacyConfig to initialize the SDK
↓
Business backend generates userSignature
↓
SUDOP.auth to complete user authentication
↓
SUDOP.startGame(gameId, listener) to launch the game
↓
Add the game View in onGameViewCreated
↓
Set orientation, register the business delegate, and save the game handle in onCreated
↓
Receive loading progress in onProgress
↓
onSuccess: game launched successfully
↓
Release game resources when the page exits11. Notes
- Complete advertising integration and applicable consent flows before calling
initSDKduring app startup. - User authentication via
authmust be completed before launching a game. - The
userSignatureshould be generated by the business backend; assembling sensitive signature parameters on the client is not recommended. - After the
onGameViewCreatedcallback, you need to add the game View to your own business container. - In the
onCreatedcallback you can set the screen orientation, register the business delegate, set the game state, and so on. onProgresscan be used to display game loading progress.- In
onFailure, displaying an error message and retrying as needed is recommended. - Always release game resources when the page is destroyed to avoid resource leaks.
12. Release Checks
- Verify required
INTERNETandACCESS_NETWORK_STATEpermissions in the final Merged Manifest, plus the correct app ID when using AdMob. - When using GAID, check the
AD_IDpermission under the conditions above. - Ensure the privacy policy and store data disclosures match actual collection and sharing by the app and ad SDKs.
