Dynamic Price for GAM

Integrating Nimbus into your Google Ad Manager Setup

Dynamic Price Integration

Dynamic Price allows publishers to integrate their Nimbus auctions into their Google Ad Manager (GAM) setup. The Nimbus win response is appended to a GAM ad request, enabling Nimbus to compete within the GAM auction. GAM will determine the winner and render the creative.

This requires publishers to work with the Nimbus team to determine their breakdown of price granularities (also known as line items). These will be used in both the Nimbus SDK setup as well as in the GAM dashboard. These must always match in order for Dynamic Price to function properly.

Setup your Line Items

What you need to do first

The following steps need to occur before any integration can be started. These steps are crucial to success and will be used throughout the rest of the process by both engineering and account teams.

1. In the Admin section, under Companies, create “Nimbus” as an ad network

2. Grant Nimbus access for line item creation

The following permissions are needed:

DFP admin privileges for the account
API access enabled for the account

3. Adding Nimbus to your GAM Account

Nimbus information you will need to add to your GAM account before line items can be set up:

In the Inventory section, please create the following key-values and select the following:
1. Please create “na_id”. Set the the key-value as Dynamic and Non-Reportable
2. Please add in “na_bid”. Set the key-value as Dynamic and Reportable
3. Please also add “na_bid_video“ (video key value). Set the the key-value as Dynamic and Reportable
4. Please create “na_duration” (video key value). You can leave the key value as Dynamic and Non-Reportable
In the Ad Units section - if you have specific ad unit targeting you would like to set, please ensure the following:
1. Ensure Nimbus has permission to see and edit the ad unit(s)
2. Please let us know which ad unit(s) or placement(s) you would like Nimbus to target
3. If no ad unit is desired, the Nimbus lines will be set to “Run of Network”

4. Determine all price granularities breakdowns

This is the complete list of intervals that will be called for ad requests and should be created and agreed upon with your Nimbus account manager. A sample price granularity breakdown looks like this:

Example of price granularities breakdowns:

 $0.01- $5.00 > in $0.01 increments
 $5.00 - $10.00 > in $0.10 increments
 $10.00 - $20.00 > in $0.50 increments

These breakdowns will then be used by Nimbus in setting up GAM line-items and by your engineering team in your Nimbus SDK setup.

5. The Nimbus team will create all your production and testing line items according to your price granularities before you can move forward.

Activating Dynamic Price in the Nimbus SDK

Using your prepared price granularity breakdowns

You can now request an ad via your Dynamic Price setup in the Nimbus SDK. You should be familiar with this process from the Requesting section of the Nimbus documentation.

To note before starting:

The value of the positionName string passed to the nimbus request must represent a consistent value across every request that defines the ad unit in which the ad is located. It will be visible in the Nimbus Dashboard and is used to group requests logically by where the ad exists in the application.
The parameters of ad request to Nimbus must match the Google ad container it would be served into; i.e. no video or hybrid request being targeted to a 320x50 banner sized ad placement.
If implementing Dynamic Price alongside other Ad Networks, it is required that all requests to each network are called at the same time.

1. In your build.gradle, include the following line in your dependencies block.

dependencies {
    implementation("com.adsbynimbus.android:extension-google:${sdkVersion}")
}

2. Performing a Dynamic Price Request

Create an instance of the NimbusAdManager class

val nimbusAdManager = NimbusAdManager()

Create an instance of a NimbusRequest using the helper methods provided in the Nimbus SDK.

// Default format
val nimbusRequest = TODO("This request should match the ad type and size of the target Google ad")

// 320x50 Banner Example
val nimbusRequest = NimbusRequest.forBannerAd({positionName}, Format.BANNER_320_50, Position.FOOTER)

// Banner and Video Example
val nimbusRequest = NimbusRequest.forInterstitialAd({positionName})

Add the previously determined pricing granularities

Please consult your Nimbus Account Manager before making any changes to price granularities.

val priceMapping = LinearPriceMapping(
    LinearPriceGranularity(0, 100, 1),
    LinearPriceGranularity(100, 1000, 100),
    …
)

Make the request to Nimbus and apply Dynamic Price

lateinit var googleAdRequestBuilder: AdManagerAdRequest.Builder
nimbusAdManager.makeRequest(context, nimbusRequest, object : RequestManager.Listener {
    override fun onAdResponse(nimbusResponse: NimbusResponse) {
        googleAdRequestBuilder.applyDynamicPrice(nimbusResponse, 
            priceMapping /* this parameter is optional if using defaults */)
        TODO("build and send googleAdRequestBuilder to google")
    }

    override fun onError(error: NimbusError) {
        TODO("No winning bid or a network error occurred. Continue to request Google ad")
    }
})

As a reminder, if implementing Dynamic Price alongside other Ad Networks, it is required that all requests to each network are called at the same time. Responses from all networks including Nimbus must be received prior to appending the key-value pairs from each response into the GAM request.

Testing

How to confirm your setup and some common issues

You can set test mode to true in the Nimbus SDK to confirm your Dynamic Price integration. The Nimbus team will set up line items in your GAM dashboard for testing purposes.

Contact your Nimbus Account Manager to ensure testing is enabled in the GAM Dashboard and to confirm successful results or any issues to address.

Troubleshooting

The serving of ads in a production environment is entirely dependent on the correct setup of the line items in GAM. The symptoms of an incorrect setup are not distinguishable from the symptoms of Nimbus losing the auction to Google or another bidder. If Nimbus line items are not delivering, the first place to look is the integration itself. Some troubleshooting steps include:

Confirm that line items were set up correctly in GAM and code
Confirm that line items and not yield groups are being used
Confirm that line items are in the delivering state
Confirm that test mode is disabled
Confirm that requests are being made simultaneously
Confirm that floors are competitive among all bidders
Confirm the currency of the GAM price granularities is set to USD

Launching

When you’re ready to launch, there’s only a few things to double-check to ensure success

1. Turn off test mode

Set test mode to false in the Nimbus SDK.

2. Confirm timing with your Account Manager

The Nimbus team will:

Confirm your desired ad unit targeting.
Switch from testing to final production line items.
Enable GAM Storage in your GAM account.

3. Launch!

After going live, the production line items should begin successfully delivering ads, indicating that the line items are working as intended.