Amazon Publisher Services integration guide

Before you start

Amazon Publisher Services (APS) is an invitation-only program that currently supports interstitial and banner/MREC ads. To integrate the APS, you will need to integrate and initialize both the ironSource SDK and APS SDK. Make sure you perform the full integration flow as detailed below to display APS ads in your application.

Supporting APS Android SDK Range 

The APS Adapter 4.3.9 for Android is designed to integrate the APS Android SDK through a range dependency. By using the 9.8+ dependency, you will be able to automatically integrate to any future APS Android SDK (<9.8.8), without integrating a new LevelPlay adapter.

Step 1. Create an APS account

  1. Reach out to APS to set up your app’s account. To create an APS account, go to the APS website, click the “contact us” button, and open a request.
  2. If your APS request is approved, you will receive an invitation link to sign up and create your account with APS.
  3. The above steps must be completed before you proceed to set up APS in LevelPlay. 

Step 2. Set up your slots in APS Network

  1. Choose the right application from the apps menu and click on setup
  2. Choose ironSource LevelPlay as your monetization service setup menu
  3. Add slots and define for each slot :
    1. Name
    2. Ad size
    3. Price points (auto/manual)
  4. Finish adding all slots and pick up your credentials:
    1. Get your app id
    2. Download the price point CSV file

Step 3. Activate APS Network

Inside the ironSource platform, access the SDK Networks setup to configure APS parameters into your ironSource account.

  1. Once you have the credentials mentioned above, log in to your ironSource account and go to Monetize ➣ Setup SDK Networks
  2. Select APS from the table of Available Networks and click on the Activate button
  3. Select APS from the list of ad networks and click Setup.
  4. Enter your APS app ID and upload CSV file as is.

Step 4. Add the APS adapter to your build

Gradle

  1. Make sure the following Maven URL exists in your build.gradle script of your app module
    repositories {
        mavenCentral() 
        maven { 
             url 'https://android-sdk.is.com/' 
         }
    }

  2. Add the adapter’s Maven name to your build.gradle script of your app module.
    dependencies {
        implementation ('com.amazon.android:aps-sdk:9.8.+') 
        implementation ('com.ironsource.adapters:apsadapter:4.3.11')
    }

Step 5. Update AndroidManifest.xml

Manifest Permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Manifest Activities:

<activity android:name="com.amazon.device.ads.DTBInterstitialActivity"/>
<activity android:name="com.amazon.device.ads.DTBAdActivity"/>

For Proguard Users Only

If you are using ProGuard with the APS adapter, you must add the following code to your ProGuard file:

-keep class com.amazon.device.ads.** { *; }

Step 6. Init APS SDK

The APS network requires that you initialize both the ironSource and APS SDKs to display APS ads. 

Initialize the APS SDK as soon as your application is opened and before initializing the ironSource SDK. Use the APS App ID, defined in Step 2 of the APS setup. 

AdRegistration.getInstance(APS_APP_ID, this);
//Where 'this' is an activity context.

Step 7. Share APS Bid info with ironSource mediation per ad

Before loading each ad, call the APS API to get the load info that is required for ironSource SDK to load an ad.

These are the required steps: 

  1. Load the APS ad request before each ironSource ad unit load.  
  2. Call SetNetworkData to share the APS bid info with ironSource.
  3. Load the relevant ad unit using ironSource mediation APIs.

Load banner/MREC ads

  1. Call the APS banner ad request before each ironSource ad unit load. Use the Slot UUID when creating the load ad request.
    final DTBAdRequest loader = new DTBAdRequest();
    loader.setSizes(new DTBAdSize(SLOT_WIDTH, SLOT_HEIGHT, "Your_Slot_UUID"));
    loader.loadAd(new DTBAdCallback()); 
    

  2. If the APS ad was loaded successfully, share the ad data with ironSource. This should include the following parameters:
    1. Bid Info: Information required for the Amazon ad to be displayed
    2. Price Point Encoded: The winning ad price, as returned from APS
    3. UUID: Slot unique identifier
    4. Width: The banner width
    5. Height: The banner height

    public void onSuccess(DTBAdResponse dtbAdResponse) {
        // Append the APS bid parameters to ironSource mediation to add APS to the next ad request 
        JSONObject apsDataJsonBN = new JSONObject();
        apsDataJsonBN.put("bidInfo", SDKUtilities.getBidInfo(dtbAdResponse));
        apsDataJsonBN.put("pricePointEncoded", SDKUtilities.getPricePoint(dtbAdResponse));
        apsDataJsonBN.put("uuid", slotUUID);
        apsDataJsonBN.put("width", dtbAdResponse.getDTBAds().get(0).getWidth());
        apsDataJsonBN.put("height", dtbAdResponse.getDTBAds().get(0).getHeight());
    
        // Define APS data per interstitial ad unit 
        JSONObject apsDataJson = new JSONObject(); 
        apsDataJson.put(IronSource.AD_UNIT.BANNER.toString(), apsDataJsonBN);
        IronSource.setNetworkData("APS", apsDataJson);
    }
    

    If APS returns no fill, call LevelPlay’s loadBanner()

  3. Load ironSource banner ad.
    Learn more here.
    Banner refresh mechanism If you choose to use ironSource’s automatic refresh mechanism, make sure to call APS load ads after each impression.  This will ensure that the APS banners will be able to participate in the next auction, as well. If you do not want to maintain this logic, simply cancel the refresh mechanism and load each ad manually after destroying the previous ad.

    Load Interstitial ads  

    1. Call APS interstitial ad request, before each ironSource ad-unit load. Use the Slot UUID when creating the load ad request.
      final DTBAdRequest loader = new DTBAdRequest();
      loader.setSizes(new DTBAdSize.DTBInterstitialAdSize(YOUR_INTERSTITIAL_UUID));
      loader.loadAd(new DTBAdCallback());

      ironSource supports APS interstitial video ads, starting from APS adapter 4.3.3. To load an interstitial video, call the following method:

      if your app is in portrait mode:

      final DTBAdRequest loader = new DTBAdRequest();
      loader.setSizes(new DTBAdSize.DTBVideo(320, 480, YOUR_INTERSTITIAL_VIDEO_UUID));
      loader.loadAd(new DTBAdCallback());
       

      if your app is in landscape mode:

      final DTBAdRequest loader = new DTBAdRequest();
      loader.setSizes(new DTBAdSize.DTBVideo(480, 320, YOUR_INTERSTITIAL_VIDEO_UUID));
      loader.loadAd(new DTBAdCallback());
       

    2. If the APS ad was loaded successfully, share the ad data with ironSource. This should include the following parameters:
      1. Bid Info: Information required for the Amazon ad to be displayed
      2. Price Point Encoded: The winning ad price, as returned from APS
      3. UUID: Slot unique identifier

      public void onSuccess(DTBAdResponse dtbAdResponse) {
          // Append the APS bid parameters to ironSource mediation to add APS to the next ad request 
          JSONObject apsDataJsonIS = new JSONObject(); 
          apsDataJsonIS.put("bidInfo", SDKUtilities.getBidInfo(dtbAdResponse));
          apsDataJsonIS.put("pricePointEncoded", SDKUtilities.getPricePoint(dtbAdResponse));
          apsDataJsonIS.put("uuid", slotUUID);
      
          // Define APS data per interstitial ad unit 
          JSONObject apsDataJson = new JSONObject(); 
          apsDataJson.put(IronSource.AD_UNIT.INTERSTITIAL.toString(), apsDataJsonIS);
          IronSource.setNetworkData("APS", apsDataJson);
       }

      If APS returns no fill, call LevelPlay’s loadInterstitial().

    3. Load ironSource interstitial ad.
      Learn more here.

    Rewarded Video ads

    The APS integration differs according to the rewarded video operation mode that you implement in your app. 

    1. Manual loading mode: This is the recommended setup to integrate with APS. This will require you to call APS ad requests before each rewarded video load. 
    2. Rewarded video default mode (automatic): When using the LevelPlay default mode for displaying rewarded videos, you’ll need to load the first APS ad, before initializing the ironSource SDK, and after initializing the APS SDK. In addition, we recommend calling the next APS load request before each show, to affect the next waterfall request.

    Load Rewarded Video ads

    1. Call the APS rewarded video ad request before each ironSource ad unit load (or before the show, in automatic mode). Use the Slot UUID when creating the load ad request.
      if your app is in portrait mode:
      final DTBAdRequest loader = new DTBAdRequest();
      loader.setSizes(new DTBAdSize.DTBVideo(320, 480, YOUR_REWARDED_VIDEO_UUID));
      loader.loadAd(new DTBAdCallback());

      if your app is in landscape mode:
      final DTBAdRequest loader = new DTBAdRequest();
      loader.setSizes(new DTBAdSize.DTBVideo(480, 320, YOUR_REWARDED_VIDEO_UUID));
      loader.loadAd(new DTBAdCallback());

    2. If the APS ad was loaded successfully, share the ad data with ironSource. This should include the following parameters:
      1. Bid Info: Information required for the Amazon ad to be displayed
      2. Price Point Encoded: The winning ad price, as returned from APS
      3. UUID: Slot unique identifier
        public void onSuccess(DTBAdResponse dtbAdResponse) {
            // Append the APS bid parameters to ironSource mediation to add APS to the next ad request 
            JSONObject apsDataJsonRV = new JSONObject(); 
            apsDataJsonRV.put("bidInfo", SDKUtilities.getBidInfo(dtbAdResponse));
            apsDataJsonRV.put("pricePointEncoded", SDKUtilities.getPricePoint(dtbAdResponse));
            apsDataJsonRV.put("uuid", slotUUID);
            // Define APS data per rewarded video ad unit 
            JSONObject apsDataJson = new JSONObject(); 
            apsDataJson.put(IronSource.AD_UNIT.REWARDED_VIDEO.toString(), apsDataJsonRV);
            IronSource.setNetworkData("APS", apsDataJson);
         }

        If APS returns no fill, call LevelPlay’s loadManualRewardedVideo().

          Done!

          You’re now ready to deliver APS demand within your application.


          What’s Next?
          To leverage additional ad networks through LevelPlay, integrate the network adapters and follow our integration guides.