Testing Audience Network Implementation

When you're integrating Facebook Audience Network into your mobile website or app, you should test your implementation on physical devices with production ads before rolling it out. Use the latest Audience Network SDK in your integration to include the most recent bug fixes and improvements. The following sections provide step-by-step guidance on how to test Audience Network ads integration with your app or mobile website.

Step 1: Test with Production Ads

Step 2: Check for Error Codes of Production Ads Requests

Step 3: Use Audience Network Requests Debugger for Ads Requests Diagnosis

Step 4: Testing with Test Ads

Step 5: Audience Network Ads Integration Checklist

Step 1: Test with Production Ads

Testing with production ads is a two-step process. The first step is to add people to your business settings page to enable them to see production ads before the app is approved. The second step is for assigned testers to use your app or mobile website while logged in to Facebook.

Adding Testers To Your App

You can test your app or mobile website on physical devices with production 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 Business Settings.
  2. Click +Add on the People tab on the left.
  3. Type the email address of the person you want to your account in Business Manager. You can enter multiple people here.
  4. You can assign people roles if you wish or you can click Skip to only add them to your account in Business Manager.

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 and make sure your testers are added to your business manager settings page.
  2. Each of the people 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 person in your business in order to return an ad.
  3. The person testing can now launch your app and trigger the placements that you want to test. They should see a production 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.

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.



Step 2: Check for Error Codes of Production 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.

1011 - Display Format Mismatch

Server Response SDK Documentation

Code=1011 “Display Format Mismatch”

  • Error 1011 - Display Format Mismatch due to:
  • The display format in the ad request does not match the display format specified for this placement.
  • Each placmeent can only be used with a single display format.
  • You can create multiple placements in order to use different display formats.

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.


Step 3: Use Audience Network Requests Debugger for Ads Requests Diagnosis

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.

  1. Go to Monetization Manager
  2. Click Manage property
  3. Click on Property Settings > Request Debugger on the top right
  4. Click on Start to monitor the requests from your app or website.

On your actual iOS or Android test device, iOS or Android, navigate in your app to trigger Audience Network ad placements. 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 the simulator/emulator
  2. Ensure the Facebook app is installed on your test device
  3. Ensure the tester is logged in to Facebook on their test device also has a role in your business
  4. If using mediation, ensure the mediation layer is sending requests to Facebook Audience Network


Step 4: Testing with Test Ads

You should ensure that the user testing your app is added to a role on your app's Business Manager. This is the recommended testing method as it lets you see production ads on physical devices. See the Testing With Production 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 UI of production 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 production 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.

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.

Test Ad Type Table

Test Ad Type Description Supported Ad Format

VID_HD_16_9_46S_APP_INSTALL

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

Interstitial, Rewarded Video, Native

VID_HD_16_9_46S_LINK

16x9 HD video 46 sec ad with link CTA option

Interstitial, Rewarded Video, Native

VID_HD_16_9_15S_APP_INSTALL

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

Interstitial, Rewarded Video, Native

VID_HD_16_9_15S_LINK

16x9 HD video 15 sec ad with link CTA option

Interstitial, Rewarded Video, Native

VID_HD_9_16_39S_APP_INSTALL

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

Interstitial, Rewarded Video, Native

VID_HD_9_16_39S_LINK

9x16 HD video 39 sec ad with link CTA option

Interstitial, Rewarded Video, Native

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

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

When testing your ad placements with test ad type, please pay attention to Supported Ad Format. For example, if you create Rewarded Video Instance to request ad with test ad type IMG_16_9_APP_INSTALL, you will get display error.

Example to request test ads in code on iOS devices

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 will see a message like this printed in the Logcat when testing on a physical Android device:

#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.

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 physical 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.



Step 5: Audience Network Ads Integration Checklist

  1. Install and log in to the Facebook app in your test device.
  2. Add people who are testing your Audience Network ads to your account in Business Manager.
  3. Make sure you initialize the ad instance with the placement ID created from your Business Manager. Refer to Getting Started step.
  4. Check if Audience Network production ads were requested successfully by your app. Use Audience Network Error Codes and Audience Network Requests Debugger for diagnosis.
  5. Check if ads are fully visible and clear to users of your app.
  6. Check the user experience of your ads integration using testing ads. Make sure the test ad code snippet is removed before launching to the app store. Otherwise, your production app will only show test ads.