Mobile App Bidding Integration Troubleshooting

When you've finished server-to-server or client-to-server bidding integration, you should complete app bidding integration testing on physical devices with production ads. In case you are facing some http-errors or 'no bids', this session will help you troubleshoot your implementation.

Prerequisites

Sections

Use cURL to Debug Bid Requests

HTTP Error Codes and Resolutions in Bid Request

Troubleshooting No Bids

Use cURL to Debug Bid Requests

In order to debug the bid request, you can take advantage of cURL command, which allows you to send bid request and receive bid response in your terminal.

Step 1. JSON Payload for Interstitial Ad in bid request

  • Replace YOUR_PLACEMENT_ID with your placement ID
  • Replace YOUR_BUSINESS_ID with your business ID
  • Replace YOUR_DEVICE_ID with your device ID
  • Replace YOUR_BIDDER_TOKEN with your Bidder Token generated from Audience Network SDK
  • Replace YOUR_PLATFORM_ID with the mediation partner Platform ID (FB App ID).
  • In case you'd like to test with different ad format, please refer to Supported Ad Formats.
  • Save JSON payload below as bid_request.json
{
  "id": "vwxfKskkMobzQQ1e7M70",
  "imp": [
    {
      "id": "FB Ad Impression",
      "tagid": "YOUR_PLACEMENT_ID",
      "instl": 1,
      "banner": {
        "h": 0,
        "w": 0,
        "linearity": 0
      }
    }
  ],
  "app": {
    "publisher": {
      "id": "YOUR_BUSINESS_ID"
    }
  },
  "device": {
    "ua": "Dalvik\/2.1.0 (Linux; U; Android 8.1.0; Android SDK built for x86 Build\/OSM1.180201.000)",
    "ifa": "YOUR_DEVICE_ID",
    "dnt": 0,
    "ip": "125.123.255.123"
  },
  "user": {
    "buyeruid": "YOUR_BIDDER_TOKEN"
  },
  "regs": {
    "coppa": 0
  },
  "at": 1,
  "tmax": 500,
  "test": 1,
  "ext": {
      "platformid": "YOUR_PLATFORM_ID"
  }
}

Step 2. Send bid request with cURL command

  • Open your Terminal
  • Navigate to the directory where you saved your bid_request.json by cd ~/{FILE_PATH}
curl -X POST -H "Content-Type: application/json" -d @bid_request.json https://an.facebook.com/placementbid.ortb

Step 3. Check out bid response in case the bid request is valid

{
   "id": "Auction ID",
   "seatbid": [
      {
         "bid": [
            {
               "id": "Bid Response ID",
               "impid": "FB Ad Impression",
               "price": 99.99,
               "adm": "{\"type\":\"ID\",\"bid_id\":\"BID ID\",\"placement_id\":\"Placement ID\",\"resolved_placement_id\":\"Resolved Placement ID\",\"sdk_version\":\"SDK Version\",\"device_id\":\"Device ID\",\"template\":102,\"payload\":null}",
               "nurl": "https://www.facebook.com/audiencenetwork/nurl/?partner=partner_id&app=app_id&placement=placement_id&auction=auction_id&impression=impression_id&request=request_id&bid=bid_id&ortb_loss_code=0&clearing_price=${AUCTION_PRICE}",
               "lurl": "https://www.facebook.com/audiencenetwork/nurl/?partner=partner_id&app=app_id&placement=placement_id&auction=auction_id&impression=impression_id&request=request_id&bid=bid_id&ortb_loss_code=${AUCTION_LOSS}&clearing_price=${AUCTION_PRICE}"
            }
         ]
      }
   ],
   "bidid": "Bid ID",
   "cur": "USD"
}

Step 4. Look into x-fb-an-errors in HTTP response headers when you did not get above bid response.

cURL command to display the HTTP response headers.

url -X POST -H "Content-Type: application/json" -v @bid_request.json https://an.facebook.com/placementbid.ortb
...
> Content-Type: application/json
>
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
< HTTP/2 400
< x-fb-an-request-id: fb_an_request_id
...
< x-fb-an-errors: Value cannot be null: value given: null
...

Please refer to HTTP Error Description and Resolutions in Bid Request to fix your bid request.

HTTP Error Description and Resolutions in Bid Request

When testing your bidding implementation regardless of Server-to-Server or Client-to-Server, you may experience one of several possible error codes when making a bid request. These error codes and resolutions are described below.

400 Response: Invalid Parameter Errors

Error Message Description Resolution

Invalid bidder token in user.buyeruid

The bidder token in user.buyeruid is not valid.

How to generate valid bidder token:

  • Android - BidderTokenProvider.getBidderToken(context);

  • iOS — [FBAdSettings bidderToken];

ipaddress must be a valid IP address

In device object of bid request payload, you should provide valid IP address for ip(v4) or ipv6 field.

Correct Examples:

  • ip(v4): 255.255.255.0

  • ipv6: 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Incorrect Examples: (Do not truncate your ip)

  • ip(v4): 255.255.255

  • ipv6: 2001:0db8:85a3:0000:0000:8a2e

valid placementids are required

In imp.tagid field, you should provide valid Audience Network Placement ID.

Please find your Placement ID from your Business Manager. Choose Manage Properties and find Placement ID under Ad Space of Android or iOS platform.

Publisher ID is not set on the app request.

app.publisher.id field is not set in the request.

Please find your Publisher ID from your Business Settings. Choose Apps in the left menu and find your App ID as your Publisher ID

all placementids must be for same appid

As the message indicates, all Audience Network Placement IDs in the bid request should belong to same App ID.

Please check whether all Placement IDs in the bid request belong to same App ID from Business Manager. Choose Manage Properties and find Placement IDs under Ad Space of Android or iOS plaftform.

Value does not contain the non-optional and non-nullable shape field

Required values are missed in your bid request.

Required Values:

  1. id

  2. imp, imp.tagid, imp.id

  3. app.publisher, app.publisher.id

  4. device

  5. ext, ext.platformid

  6. at -- Enum (1, 2) value required

adformats are required, the number of adformats and placementids should be the same

Please provide non-empty and valid adformats.

Supported Ad Formats:

  • Native format: {'id': ${AUCTION_ID}, "native": { "h": -1, "w": -1 }, 'tagid': ${PLACEMENT_ID}}

  • Native banner format: {'id': ${AUCTION_ID}, "native": { "h": -1, "w": -1 }, 'tagid': ${PLACEMENT_ID}}

  • Interstitial format: {'id': ${AUCTION_ID}, "banner": { "h": 0, "w": 0 }, 'tagid': ${PLACEMENT_ID}, 'instl': 1}

  • Rewarded Video format: {'id': ${AUCTION_ID}, "video": { "h": 0, "w": 0, 'ext': { 'videotype': 'rewarded' } }, 'tagid': ${PLACEMENT_ID}}

  • Banner format - height 50: {'id': ${AUCTION_ID}, "banner": { "h": 50, "w": -1 }, 'tagid': ${PLACEMENT_ID}}

  • Banner format - height 250: {'id': ${AUCTION_ID}, "banner": { "h": 250, "w": -1 }, 'tagid': ${PLACEMENT_ID}}

  • Instream Video format: {'id': ${AUCTION_ID}, "video": { "h": 0, "w": 0, 'linearity': 1 }, 'tagid': ${PLACEMENT_ID}}

Please check Supported Ad Formats for more information.

banner, native and video objects are mutually exclusive but one of them is required

For above adformats, there are different objects: native, banner and video. Our endpoint requires one of these 3 objects, but be careful they are mutually exclusive.

Please refer to above Supported Ad Formats resolutions.

400 Response: Unmatched User or Unauthorized Errors

Error Message Description Resolution

No user match (are cookies passed, and user logged in?)

Our backend is unable to match the request for Facebook User. User not logged into Native Facebook App on Mobile Device.

Please ensure you have Facebook User logged in Mobile (Android/iOS) Facebook App.

No app matched for domain and business ID

In case you use Business ID in app.publisher.id field, our backend is unable to find out the app by domain and business.

If you keep seeing this error, please use app id in app.publisher.id field.

Application not authorised for app bidding

Application ID in app.publisher.id is not whitelisted for bidding, or application is pending review.

Please contact us to get your app whitelisted, or wait for app approval.

Platform not authorised for app bidding

Platform ID in ext.platformid is not whitelisted for bidding. Please make sure your app id is whitelisted and not pending review.

Resolutions:

  1. If you are a publisher, your app ID is same as platform ID.

  2. If you are a partner, your publisher will put different values in ext.platformid (partner app ID) and app.publisher.id. (publisher app ID)

Please contact us to get your app whitelisted, or wait for app approval.

unexpected error

Reasons:

  1. App/User Throttling.

  2. Application is rejected.

  3. Untrusted Installer.

  4. Fradulent request.

Resolutions:

  1. Please re-load ad less frequently.

  2. Please contact us to check your application status.

  3. Please ensure you install your app from Trusted App Store.

  4. Please contact us if keep seeing this error.

204 Response: Empty Error Message

Error Message Description Resolution

Empty in Error Header of x-fb-an-errors from bid response

Reasons:

  1. For case of dnt: 1 -- do-not-track, Facebook won't bid.

  2. imp.instl is missing for interstitial ad format.

Resolutions:

  1. User has to turn on Advertising Tracking in the device and then the client should pass dnt: 0 (do-not-track) in bid request, then Faceook will bid.

  2. Please ensure you have imp.instl field with 1 in order to bid for interstitial ad.

  3. If keep seeing 204 response, please contact us.

Troubleshooting No Bids

  • Make sure you are capturing and logging the x-fb-an-errors HTTP header to help you understand the cause of an error.
  • Ensure the Facebook app is installed on the device where your app is running and you are logged into Facebook with your real user account. Fake or testing Facebook user accounts are a violation of Facebook's policy and will be disabled.
  • Ensure you are getting the bidder token from the Audience Network SDK by calling com.facebook.ads.BidderTokenProvider.getBidderToken() on Android and [FBAdSettings bidderToken] on iOS and sending the returned string into buyeruid field of the bid request.
  • Ensure you are sending the correct device id in ifa field in the bid request (Android -- AdvertisingIdClient.getAdvertisingIdInfo(context).getId(), iOS -- [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString]).
  • Ensure that the do-not-track(dnt) is not enabled on your device, and then pass dnt: 0 (do-not-track) in bid request.