Integrating the Android SDK

This guide describes integrating the DT Exchange SDK into your Android project, which uses Maven Central for dependency management. 

Note

This guide describes an older version of the DT Console's user interface. If you have already switched to the newer user interface released in September 2024, refer to the updated documentation.

Prerequisites

Android 4.1 (API Level 16)+

Step 1: Integrating the SDK in your App

DT supports both Maven Central dependencies and manual downloads to integrate the SDK. 
From the accordion drop-down list, select one of the following options:

Configuring Maven Central    

  1. Add the following to the app project-level build.gradle file to the allprojects repository (not buildscript):
allprojects {
  repositories {
    // add this
    mavenCentral()
  }
  // ...
}
  1. From the app-level build.gradle file, add the following script to the dependencies section.
dependencies {
    // ...
    implementation "com.fyber:marketplace-sdk:8.3.5"
    // ...
}

 

Manually Downloading the SDK

To download the DT Exchange Android SDK, click here:

  1. Log in or register your account.
  2. Copy the following files from the InneractiveAdSDKfolder to your project libs folder.
    • For version 8.3.5:
      fyber-marketplace-8.3.5.aar
    • For version 8.1.0 and above (for Open Measurement support):
      fomsdk-android-1.5.1-release.aar
  3. Add the following repositories and dependencies to the project build.gradle file:
repositories { 
    // ... 
    // Add a flat dir repository 
    flatDir { 
       dirs 'libs' 
    } 
}

dependencies { 
   // Add the marketplace AAR libraries
   implementation (name:"fyber-marketplace-8.3.5", ext:'aar')
   // add open measurement sdk - fyber marketplace 8.1.0 and above
   implementation (name:"omsdk-android-1.5.1-release", ext:'aar')
}

Step 2: Integrating Google Play Services

DT recommends using Google Play Services to access your Google Advertising ID. As increasing advertising campaigns requires it, ad inventory is limited without the ID, which is essential for tracking your app's daily active users (DAU).

  1. In the app-level build.gradle file, add the following dependencies:
dependencies  {
    implementation ('com.google.android.gms:play-services-base:Version#')
    // use only the ads identifier library
    implementation ('com.google.android.gms:play-services-ads-identifier:x.y.z') 
// or implementation ('com.google.android.gms:play-services-ads:x.y.z') }
  1. For apps targeting API level 31 (Android 12) or higher, add the following script to declare the Google Play Services permission in the AndroidManifest.xml file.
    This step is required unless the app uses a recent Google Mobile Ads SDK version.  

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

For further information about Google Advertising ID Restrictions, read the following:

Google Advertising ID Restrictions

Google Advertising ID (GAID) is a unique string identifier that anonymously identifies a device for advertising purposes. Google Play Services provides this Advertising ID and enables users to opt out of personalized ads in apps or reset their identifier. When a user resets their identifier, it cannot be connected to a previous identifier.

Permission Required for Advertising ID

In 2021, Google announced a behavior change for apps targeting Android 13 (API Level 33) and higher, the AD_ID permission is required. For more information, see Advertising ID.

To receive the Advertising ID, developers must add a new permission to the manifest file unless the app uses a recent version of the Google Mobile Ads SDK:

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Recent versions of the Google Mobile Ads SDK (play-services-ads v20.4.0 and higher, or play-services-ads-identifier v17.1.0 and higher) include this permission. If the app uses these SDKs, the AD_ID permission from the SDK's library manifest merges with your app's main manifest by default, making the Advertising ID available.

For more information about Google Play Services, see Set Up Google Play Services.

Step 3: Adding Mandatory Permissions - Android Manifest File

  1. Add the following mandatory permissions to the AndroidManifest.xml file:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

 

Tip

ACCESS_NETWORK_STATE differentiates WiFi from a cellular network.

  1. To enhance targeting capabilities, add this permission:
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Step 4: Initializing the SDK

SDK initialization is mandatory because the DT SDK relies on the Console configuration for functionality. No ad units will display without this configuration, and the SDK will not operate. DT recommends that you perform it at the app's initialization stage. Follow these steps to initialize the SDK.

Google Play Families Ads API

To participate in the Google Play Families Ads program, run the following code to indicate if the user is a child:

InneractiveAdManager.currentAudienceIsAChild();

Tip

The API is called once per app session before the SDK is initialized. If the app doesn't contain the API, the user is not a child user by default.

After configuring your Android Manifest and preparing to request ads, initialize  InneractiveAdManager.initialize(context, <"appID">), and pass on your Activity or application context with the following code :

public class MainActivity extends Activity {
 
   @Override
   protected void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.activity_main);
      InneractiveAdManager.initialize(this, "Enter_Your_DT-Exchange_AppID"); 
   }
 
   @Override
   protected void onDestroy() {
      if (isFinishing()) {
           //Optionally destroy the SDK after the activity has been destroyed
InneractiveAdManager.destroy(); } } }

*Call InneractiveAdManager.destroy() when you no longer need the library to display more ads and release any resources used by the SDK.

Tip

If you intend to destroy the library from within your activity's onDestroy method, ensure that the activity has finished.

Tip

You can change the DT library logging level. 

Locating the App ID

Follow the steps below to locate your App ID:

  • From the left menu, click Apps.
    The App Management window appears.
    Screen_Shot_2022-08-02_at_11_54_10.png
  • The corresponding App ID appears in the App ID column.

    Screen_Shot_2022-08-02_at_11_57_11.png

Initialization Callback

You can use the following initialization callback to the  InneractiveAdManager to monitor the SDK's initialization status:

InneractiveAdManager.initialize(context, appId, new OnFyberMarketplaceInitializedListener() {
           @Override
           public void onFyberMarketplaceInitialized(FyberInitStatus status) {
               // ...
           }
});

Valid Values:

  • SUCCESSFULLY: SDK initialized successfully.
  • FAILED_NO_KITS_DETECTED: Only the core DT Exchange library detected. Check dependencies and add the video-kit and  mraid-kit.
  • FAILED: SDK failed to communicate with servers. Retry initialization.
  • INVALID_APP_ID: Incorrect app ID. Verify configuration or contact support.

Important

DT recommends using the SDK and performing ad requests when the FyberInitStatus  is FAILED, as the SDK attempts to re-initialize itself internally when an AdRequest is executed. The above callback is not invoked in such cases.

Passing a User ID to the SDK

To set a User ID for the SDK session, run the following code:

Tip

The initial method of the SDK must be called in advance, and there is no need to wait for the onFyberMarketplaceInitialized  callback.

String userId = ...;
//Without reflection, using an import of the InneractiveAdManager class -
InneractiveAdManager.setUserId(userId);

//Optionally, using reflection as an example -
Class FyberInneractiveAdManagerClass = 
Class.forName("com.fyber.inneractive.sdk.external.InneractiveAdManager"); Method setUserIdStaticMethod =
FyberInneractiveAdManagerClass.getDeclaredMethod("setUserId", String.class); setUserIdStaticMethod.invoke(null, userId);

The basic Android SDK is complete. You can proceed and integrate other ad types as required. For more information, see Android Ad Formats.

Info

Review the below GDPR-related instructions (available starting Android v7.1.5 SDK and legacy version v6.5.6)

Step 5: Adding User Consent

User consent mechanisms are essential to comply with various data protection laws. The following regulations mandate that user's data be handled with explicit consent:

GDPR

The General Data Protection Regulation of the European Union (GDPR) requires you to implement a user consent mechanism. A user could be within the GDPR scope for your app when one or all of the following apply:

  • The user is currently located in the EU.
  • The user has registered with the app as an EU resident.
  • The app is specifically targeted to EU users.

Note

When you set a GDPR consent value for a user, DT assumes that the user is subject to GDPR rules, even if the user is outside Europe. If your legal assessment concludes that your non-EU users are not subject to GDPR, do not set any consent value for them.

Important

DT recommends that you consult a legal advisor to determine the best approach for your business. We also highly recommend collecting user consent with a certified Consent Management Platform (CMP).

For a complete list of CMPs, see Interactive Advertising Bureau - CMP List.

To incorporate GDPR consent values, run the GDPRConsent API in Boolean format, for example:

/**
     * Set the general data protection regulation user consent status
     * @param wasConsentGiven
     */
    public static void setGdprConsent(boolean wasConsentGiven) {…}
    
    // Calling the consent method
    
    InneractiveAdManager.setGdprConsent(true);

    /**
    * Set the general data protection regulation consent string
    * @param gdprConsent the consent string
    */
    public static void setGdprConsentString(String gdprConsent) {…}

    // Calling the consent method

    InneractiveAdManager.setGdprConsentString("consentString");

Valid values:

  • True: Granted consent.
  • False: No consent.

Setting Consent String

Use the following API to set the GDPR consent string:


GdprConsentString is a string. To clear the consent flag and consent data, use the following API: 

InneractiveAdManager.clearGdprConsentData();

If you don't obtain the user's consent before sending the SDK, only contextual ads appear to that user.

 

Important

The second option, using a valid CMP (consent management platform), is highly recommended. It involves passing a consent string per the IAB's Transparent & Consent Framework, the most common form of consent communication worldwide and crucial for enjoying ad monetization in the EU. 

 

Note

DT recommends that the first time you gather the user's consent, you pass it onto the SDK before starting it. The SDK then considers the user's consent when initializing. In the following sessions, you only need to call the API if the user updates their consent.

See GDPR Resource Page and FAQs for further information.

CCPA

The California Consumer Privacy Act of 2018 (CCPA) protects the personal information of California residents and applies to all companies operating in California. If a California resident uses a mobile app developer's app, CCPA applies to the developer and every company that processes the personal information of the app's users.
For more information on CCPA and DT's practices, see the DT Resource Page and IAB CCPA Compliance Framework.

CCPA API

Use the following API to set the CCPA consent string:

/*** Setting the US privacy setting string     
* @param consentString a non empty String     
*/
public static void setUSPrivacyString(String consentString) {…}

// Calling the consent method  		     
InneractiveAdManager.setUSPrivacyString("1YNN"); 
// This is an example value when the user chooses NOT to 'opt-out'

To determine what value to use for the US Privacy String, refer to USPrivacy IAB documentation
Example values:

  • When CCPA does not apply (for example, if the user is not a resident of California), you can either skip this API or use the following value1---.
  • If the user chooses NOT to opt and is ok with advertising as usual, you can use 1YNN.
  • If the user decides to restrict advertising and opt-out, you can use 1YYN.

To clear the privacy setting flag and opt-out data, use the following API:

InneractiveAdManager.clearUSPrivacyString();

LGPD

The Brazilian General Data Protection Law, the Lei Geral de Proteção de Dados Pessoais (LGPD), mandates processing personal data for legitimate, specific, explicit, and communicated purposes.

Use the following API to set the LGPD consent value:

InneractiveAdManager.setLgpdConsent(boolean wasConsentGiven)

Valid values:

  • IALGPDConsentTypeGiven: Granted consent.
  • IALGPDConsentTypeDenied: No consent.

If the consent value is not set, the default is no consent.

COPPA

The Children's Online Privacy Protection Act of 1998 (COPPA) is a federal law that imposes specific requirements on websites and online service operators to protect the privacy of children under 13.

COPPA API for Flagging Specific Users

Android SDK 8.2.3+ supports the COPPA API, which allows publishers to flag specific end users as children as required under COPPA. I

It is the Publisher's responsibility to decide whether to use the COPPA API or to treat all users as children. For instructions on flagging all users as children, see COPPA.

Important

  • Execute the COPPA API after successfully initializing the DT SDK.
  • Pass the COPPA state after every successful init of the SDK.

Use the following API to confirm that the target audience of the application applies to COPPA:

InneractiveAdManager.currentAudienceAppliesToCoppa();

Step 6: Configure Parameters

To add gender and age parameters, run the following script:

// For gender values, see: InneractiveUserConfig.Gender
InneractiveAdManager.setUserParams(new InneractiveUserConfig()
        .setGender(InneractiveUserConfig.Gender.FEMALE)
        .setAge(35));

Step 7: app-ads.txt

The simple app-ads.txt standard helps prevent the unauthorized selling of in-app inventory and app domain spoofing.

For details on listing your Developer Website URL in the Google Play Store, see Updating/Adding a Developer Website.

Step 8: Optional - Using the DT Exchange SDK in Secure Only Mode

InneractiveAdManager.useSecureConnections(boolean useSecureConnnections)

The InneractiveAdManagerAPI enables you to control how the SDK should perform any network connections. 

By invoking this setter with a value of true all outgoing network connections from the DT Exchange, SDK will use SSL/HTTPS. The default behavior is not to use secure connections.

Important

By requesting secure-only content, you potentially decrease the demand that the SDK can render.

Info

The Android application-level secure API (network-security-config cleartextTrafficPermitted) takes precedence over this value. If you set cleartextTrafficPermitted to false and invoke the useSecureConnections setter with a value of false, the SDK behaves as if you requested secure connections only.

Back to Top ⇧