Testing Audience Network Implementation

When you're integrating Facebook Audience Network into your mobile website or app, you should test your implementation on real devices with real ads before rolling it out to production. Please make sure to use the latest Audience Network SDKs in your integration to include the latest bug fixes and improvements. The following sections provide guidance on how to test your app and web site.

When running on an iOS or Android simulator, test ads can be shown by enabling test mode and specifying the device hashed id. This is a good first step in testing your implementation. We recommend also testing on real devices with real ads following the guidance below.

1. Testing with Real Ads

2. Error Codes of Real Ads Requests

3. Testing with Test Ads

Testing requests with Audience Network Requests Debugger

After implementing the placements in your app, you can use the Audience Network Requests Debugger tool to verify that Facebook is receiving the requests from your app.

In the audience network section of the developer dashboard: https://developers.facebook.com/apps/<your_app_id>/audience-network/

Go to the "apps" section in the left panel under "Audience Network" and scroll down to see "Audience Network Requests Debugger". Click on Start button and the tool will start to monitor the requests from your app by yourself.

On you actual iOS or Android test device, iOS or Android, navigate in your app to trigger audience network ad placements, and the ad requests will show up in the tool. Please verify that the requests are sent with the right placement id, bundle package name etc.

This requires a physical device and will not work on the iOS simulator or Android emulator

You need to be logged in to the Facebook app on the same test device that you use in order to be monitored by the tool.

If the ad requests doesn't show up in the tool, it means that Facebook is not receiving the requests as expected. You can check the following items to debug:

  1. Ensure you are on a physical device not simulator/emulator
  2. Ensure the Facebook app is installed on your test device
  3. Ensure you are logged in to Facebook on your test device with a user who is admin, developer or tester on your Facebook Audience Network app
  4. If using mediation, ensure the mediation layer is sending requests to Facebook Audience Network

Testing With Real Ads

Testing with real ads is a two step process. First step is to add testers to your app settings to enable them to see real ads before the app is approved. Second step is for those testers to use your app or mobile website while logged in to Facebook. Here are details on how to perform both steps.

Adding Testers To Your App

You can test your app or mobile website on real devices with real ads by ensuring the person testing is added to your Facebook app in any role. This is the recommended method of adding testers to your app:

  1. Go to your app's dashboard and click on the Roles tab on the left.
  2. In the Testers section, click on Add Testers button. Users can also be in the Administrators or Developers roles. We recommend the Testers role for users who need to test the app or website but are not allowed to view its settings on Facebook.
  3. Type the name, fbid or username of the person you want to add as a tester and click submit. You can enter multiple people here.
  4. You should now see the people you entered as Testers.

If you are using any mediation layer, please make sure that the mediation layer is sending requests to Audience Network. If you have testing enabled on the mediation layer, it may not be sending any requests to our servers.

Testing Mobile Apps

  1. Distribute the app to your testers' devices using your preferred distribution method.
  2. Each of the testers you added needs to have the Facebook app installed on their device and log in to it using the Facebook user id that you added to the Testers role. This is required because Facebook needs to recognize the user as a Tester on the app in order to return an ad regardless of the app's review status.
  3. The tester can now launch your app and do the steps needed to trigger the placements that you want to test. They should see a real ad.

When testing your ad placements, Facebook will intentionally send a no-fill for about 20% of requests to allow you to test how your app or mobile website handles the no-fill case.

Error Codes of Real Ads Requests

When testing your implementation of the Facebook Audience Network, you may experience one of several possible error codes when making a request. These error codes are described below.

1000 - Network Error

Server Response SDK Documentation

Code=1000 “Network Error"

  • Error 1000 - Network Error. The Audience Network SDK could not reach facebook.com (http://facebook.com/)
  • Your application should attempt to make another request until the network can be reached. We recommend making incremental requests until a connection is reestablished or you declare a timeout.

1001 - No Fill

This is a common error seen while testing, and relates to a "No Fill" response; the most common reason for this is the user is not logged in to the Facebook App when testing your mobile app or not logged in to the Facebook mobile website when testing your mobile website.

Server Response SDK Documentation

Code=1001 “No Fill”

  • Error 1001 - No Fill. May be due to one or more of the following:
  • User not logged into Native Facebook App on Mobile Device
  • Limit Ad Tracking turned on (iOS)
  • Opt out of interest-based ads turned on (Android)
  • No Ad Inventory for current user
  • Your testing device must have the native Facebook application installed.
  • Your application should attempt to make another request after 30 seconds.

1002 - Ad Load Too Frequently

Server Response SDK Documentation

Code=1002 “Load Too Frequently”

  • Ad Requests are based on a combination of:
  • Device Id
  • Placement Id
  • Display Format (Banner, Interstitial, Native)
  • Your application should attempt to make another request after 30 minutes. We also suggest adjusting your Refresh Rate or Request Rate.

1203 - Not An App Admin, Developer or Tester

Server Response SDK Documentation

Code=1203 “Not An App Admin, Developer or Tester”

  • Initial request from a bundle must come from an App Admin, Developer or Tester.

2000 - Server Error

Server Response SDK Documentation

Code=2000 “Server Error"

  • Error 2000 - Server Error. Possibly due to:
  • Invalid Placement Id - Each Placement and Type has a Unique Id
  • Unsupported or Outdated version of the SDK - please download the latest version or update your Pod if using Cocoa Pods
  • Improper call/usage of the loadAd method. We suggest placing breakpoints on loadAd and any associated methods/callbacks
  • Your application should attempt to make another request after 30 seconds.

2001 - Internal Error

Server Response SDK Documentation

Code=2001 “Internal Error”

  • Error 2001 - Internal Error. The Audience Network SDK was unable to process a response from facebook.com
  • Your application should attempt to make another request after 30 seconds.
  • If this happens consistently, please file a bug report with us.

Testing with Test Ads

You should ensure that the user testing your app is added to a role on your app dashboard on Facebook. This is the recommended testing method as it lets you see real ads on real devices. See the Testing With Real Ads section for more information on the recommended testing method.

However, as noted in the previous section, you may realize that it is not always possible to test the look of real ads with your app's UI views. In addition, you cannot guarantee that the ad received by your app will be an image ad, video ad or carousel ad. Requesting real ads will not guarantee the content and format of the ad returned. What if you want to test with an ad that contains portrait video content to make sure it looks correct with your app's UI view?

To request a test ad, you will use the following test ad type string to concatenate the placement id with '#' when initializing any Facebook ad object. The placement id template for requesting test ads is TEST_AD_TYPE#YOUR_PLACEMENT_ID.

Test Ad Type Table

Test Ad Type Description Supported Ad Format

IMG_16_9_APP_INSTALL

16x9 image ad with app install CTA option

Banner, Interstitial, Native

IMG_16_9_LINK

16x9 image ad with link CTA option

Banner, Interstitial, Native

VID_HD_16_9_46S_APP_INSTALL

16x9 HD video 46 sec ad with app install CTA option

Interstitial, Native

VID_HD_16_9_46S_LINK

16x9 HD video 46 sec ad with link CTA option

Interstitial, Native

VID_HD_16_9_15S_APP_INSTALL

16x9 HD video 15 sec ad with app install CTA option

Interstitial, Native

VID_HD_16_9_15S_LINK

16x9 HD video 15 sec ad with link CTA option

Interstitial, Native

VID_HD_9_16_39S_APP_INSTALL

9x16 HD video 39 sec ad with app install CTA option

Interstitial, Native

VID_HD_9_16_39S_LINK

9x16 HD video 39 sec ad with link CTA option

Interstitial, Native

CAROUSEL_IMG_SQUARE_APP_INSTALL

carousel ad with square image and app install CTA option

Interstitial, Native

CAROUSEL_IMG_SQUARE_LINK

carousel ad with square image and link CTA option

Interstitial, Native

Example to request test ads in code on iOS devices

When using Testflight to distribute and test your app, you will not be able to see real ads in those test builds. Instead, you will need to set test mode as shown below in order to get ads from Audience Network. Each time a Testflight-distributed app asks for the the Identifier for Advertisers (IDFA), it will get a different IDFA. Normally, IDFA remains constant for a device until a user resets it manually. But when a Testflight build asks for the IDFA from the operating system, it doesn’t get the "real" IDFA. Instead, it gets a "dummy" IDFA that changes each time the app asks for it.

To resolve this issue, you can turn on the test mode to allow the test ad to be shown.

For example, to request a video test ad with a 9:16 aspect ratio and app install CTA button in your iOS app, you need to initialize an FBNativeAd object by adding following line of code:

[FBNativeAd *nativeAd = [[FBNativeAd alloc] initWithPlacementID:@"VID_HD_9_16_39S_APP_INSTALL#YOUR_PLACEMENT_ID"];

You can run the above code to request a test ad in NativeAdSample project from the Audience Network SDK sample folder.

Alternatively if you need to request test ads with random content format, you can add following line of code before loading the ad request:

#ifdef DEBUG
[FBAdSettings setLogLevel:FBAdLogLevelLog];
[FBAdSettings addTestDevice:@"HASHED_ID"];
#endif

You would see the following log message:

[FBAudienceNetworkLog/FBAdSettings:94] 
When testing your app with Facebook ad units,  
you must specify the device hashed ID to ensure the delivery of test ads, 
add the following code before loading an ad: `[FBAdSettings addTestDevice:@"HASHED_ID"]`
Test mode device hash: bd675f960298a92003630d76fa612b1706b745ab

Replace HASHED_ID with the test mode device hash printed in the log above.

You should never ship your app to the public with the above test code as it will cause only test ads to be shown. You should instead use a preprocessor macro such as DEBUG or TESTING and then use #ifdef to distinquish a test build from a release build.

When you are finished testing you should clear the test device setting using this line of code:

[FBAdSettings clearTestDevice:[FBAdSettings testDeviceHash]]; 

Example to request test ads in code on Android devices

To request a video test ad with a 9:16 aspect ratio and app install CTA button in your Android app, you need to initialize an NativeAd object by adding following line of code:

nativeAd = new NativeAd(this, "VID_HD_9_16_39S_APP_INSTALL#YOUR_PLACEMENT_ID");

Alternatively if you need to request test ads with random content format, you will see a message like this printed in the Logcat when testing on a real Android device:

Log: Test mode device hash: HASHED_ID Log: When testing your app with Facebook's ad units you must specify the device hashed ID to ensure the delivery of test ads, add the following code before loading an ad: AdSettings.addTestDevice("HASHED ID");

You can enable test ads on a device by adding the following line of code before loading an ad:

AdSettings.addTestDevice("HASHED ID");

If you wish to add multiple test devices, then simply create a List of strings to be added before loading an ad:

List<String> testDevices = new ArrayList<>();
testDevices.add("HASHED_ID_1");
testDevices.add("HASHED_ID_2");
AdSettings.addTestDevices(testDevices);

When you are finished testing you should clear the test device setting using this line of code:

AdSettings.clearTestDevices();

Example to request test ads in mediation dashboard

In addition to requesting the test ad from code, you can configure the placement id value with test ad type from your mediation dashboard if your app uses mediation. For example, if your app uses MoPub, you can edit Facebook network and set the placement id value for the native ad to be VID_HD_9_16_39S_APP_INSTALL#YOUR_PLACEMENT_ID. Your app will receive a video test ad with a 9:16 aspect ratio and app install CTA button.