Skip to content

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:

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 moduleIntegration baselineVersion information
AdMob: com.google.android.gms:play-services-adsFixed at 25.4.0Google release notes
Carty: io.carty.bidad:carty-sdkFixed at 1.11.0Carty changelog
TopOn: com.anythink.sdk:core-tpnFixed at 6.6.22.3TopOn Android integration guide
MAX: com.applovin:applovin-sdkFixed at 13.5.1MAX Android integration guide
Taku: com.anythink.sdk:core-takuFixed at 6.6.40Taku 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.

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.

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

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:

  1. Update consent information on each launch and show required forms.
  2. Provide a privacy-options entry point when required.
  3. 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 ​

java
/**
 * 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.

java
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 ​

ParameterTypeDescription
contextContextAndroid context; passing ApplicationContext is recommended
appIdStringAppID assigned by the SUD platform
appKeyStringAppKey assigned by the SUD platform
privacyConfigSUDOPPrivacyConfigHost-confirmed advertising privacy states
listenerSUDOPInitSDKListenerInitialization 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 ​

java
/**
 * Authenticate user login status
 *
 * @param userSignature userSignature
 */
public static void auth(
        String userSignature,
        SUDOPAuthListener listener
)

4.2 Example ​

java
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 ​

ParameterTypeDescription
userSignatureStringUser signature generated and issued by the business backend
listenerSUDOPAuthListenerAuthentication result callback

5. Launch the Game ​

After completing SDK initialization and user authentication, you can launch a game by gameId.

Usage ​

java
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 MethodDescription
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:

java
@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);
    }
}
deviceOrientationDescription
landscapeLandscape
portraitPortrait
autoAuto-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:

java
@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:

java
@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 ​

text
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 exits

11. Notes ​

  • Complete advertising integration and applicable consent flows before calling initSDK during app startup.
  • User authentication via auth must be completed before launching a game.
  • The userSignature should be generated by the business backend; assembling sensitive signature parameters on the client is not recommended.
  • After the onGameViewCreated callback, you need to add the game View to your own business container.
  • In the onCreated callback you can set the screen orientation, register the business delegate, set the game state, and so on.
  • onProgress can 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 INTERNET and ACCESS_NETWORK_STATE permissions in the final Merged Manifest, plus the correct app ID when using AdMob.
  • When using GAID, check the AD_ID permission under the conditions above.
  • Ensure the privacy policy and store data disclosures match actual collection and sharing by the app and ad SDKs.