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.
APS Supports iOS operating system version iOS12 and up.

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

Cocoapods

To integrate the APS SDK with Cocoapods, enter the following line in your podfile and you’re good to go!

pod 'IronSourceAPSAdapter','4.3.9.1'

Step 5. Update SKAdNetworkItems and Info.plist

Make sure to define APS SKAdNetworkItems to your Info.plist, by using this code:

<key>SKAdNetworkItems</key>
<array>
<dict>
<key>SKAdNetworkIdentifier</key>
<string>p78axxw29g.skadnetwork</string>
</dict>
</array>

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 APS App ID, defined in Step 2 of the APS setup. 

#import <DTBiOSSDK/DTBiOSSDK.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [[DTBAds sharedInstance] setAppKey: @"APS_app_id"];
  return YES;
}

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.
    DTBAdSize *size = [[DTBAdSize alloc] initBannerAdSizeWithWidth:320 height:height andSlotUUID:slotUUID];
    DTBAdLoader *adLoader = [DTBAdLoader new];
    [adLoader setSizes:size, nil];
    [adLoader loadAd:self];
    

  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

    - (void)onSuccess:(DTBAdResponse *)adResponse{ 
      
        NSString* amznPricePoint = [adResponse amznSlots];
        NSDictionary* mediationHints = [adResponse mediationHints];
        
        NSNumber* width = [NSNumber numberWithInt:adSize.width];
        SNumber* height = [NSNumber numberWithInt:adSize.height];
            
        NSDictionary* bannerData = @{@"uuid":slotUUID, @"width":width, @"height":height,  @"pricePointEncoded":amznPricePoint, @"mediationHints":mediationHints};
        NSDictionary* apsData = @{IS_BANNER:bannerData};
            
        [IronSource setNetworkDataWithNetworkKey:@"APS" andNetworkData:apsData];
       
    }

    If APS returns no fill, call LevelPlay’s load banner method.

  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.
    DTBAdSize *size = [[DTBAdSize alloc] initInterstitialAdSizeWithSlotUUID:slotUUID];
    DTBAdLoader *adLoader = [DTBAdLoader new];
    [adLoader setSizes:size, nil];
    [adLoader loadAd:self];

    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:

    DTBAdSize *size = [[DTBAdSize alloc] initVideoAdSizeWithPlayerWidth:320 height:480 andSlotUUID:slotUUID];
    DTBAdLoader *adLoader = [DTBAdLoader new];
    [adLoader setSizes:size, nil];
    [adLoader loadAd:self];

    if your app is in landscape mode:

    DTBAdSize *size = [[DTBAdSize alloc] initVideoAdSizeWithPlayerWidth:480 height:320 andSlotUUID:slotUUID];
    DTBAdLoader *adLoader = [DTBAdLoader new];
    [adLoader setSizes:size, nil];
    [adLoader loadAd:self];

  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
      - (void)onSuccess:(DTBAdResponse *)adResponse{ //svt on onSuccess
          
          NSString* amznPricePoint = [adResponse amznSlots];
          NSDictionary* mediationHints = [adResponse mediationHints];
          NSDictionary* isData = @{@"uuid":slotUUID, @"pricePointEncoded":amznPricePoint, @"mediationHints":mediationHints};
          NSDictionary* apsData = @{IS_INTERSTITIAL:isData};
              
          [IronSource setNetworkDataWithNetworkKey:@"APS" andNetworkData:apsData];
      }

      If APS returns no fill, call LevelPlay’s load banner method.

  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:
    DTBAdSize *size = [[DTBAdSize alloc] initVideoAdSizeWithPlayerWidth:320 height:480 andSlotUUID:slotUUID];
    DTBAdLoader *adLoader = [DTBAdLoader new];
    [adLoader setSizes:size, nil];
    [adLoader loadAd:self];

    if your app is in landscape mode:
    DTBAdSize *size = [[DTBAdSize alloc] initVideoAdSizeWithPlayerWidth:480 height:320 andSlotUUID:slotUUID];
    DTBAdLoader *adLoader = [DTBAdLoader new];
    [adLoader setSizes:size, nil];
    [adLoader loadAd:self];

  2. If the APS ad was loaded successfully, share the ad data with ironSource. This should include the following parameters:
    1. Mediation hints: 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

- (void)onSuccess:(DTBAdResponse *)adResponse{
    
    NSString* amznPricePoint = [adResponse amznSlots];
    NSDictionary* mediationHints = [adResponse mediationHints];
    NSDictionary* rvData = @{@"uuid":slotUUID, @"pricePointEncoded":amznPricePoint, @"mediationHints":mediationHints};
    NSDictionary* apsData = @{IS_REWARDED_VIDEO:rvData};
        
    [IronSource setNetworkDataWithNetworkKey:@"APS" andNetworkData:apsData];
}

If APS returns no fill, call LevelPlay’s load rewarded video method.

        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.