Integrating with the Fyber SDKs

We recommend a few SDK build best practices for prepping your app to go live with Fyber. Follow these below to ensure that you get the best performance for the least amount of time spent!

Developer Portal Best Practices
Fyber Dashboard Best Practices

Developer Portal Best Practices

Follow the documentation
SDK Integration on SDK start
Offer Wall Integration Methods
Rewarded Video Integration Methods
Interstitial Integration Methods
Timing your requests
Demand Partner Reporting Credentials
Maximizing Conversion Rates for Demand Partners

Follow the documentation

The Developer Portal covers all aspects of integrating our products. We provide tips and warnings to prevent potential issues that might occur. By thoroughly following the documentation, you can prevent any technical issues that might appear in certain scenarios and possibly missed during tests.

After you’ve gone through the docs and you’re set to submit your app, take another moment to give a second look to the documentation for any last updates.

SDK Integration on SDK start

Passing in Identifiers

Make sure device identifiers are available to the integration.

The most commonly used and most important device identifiers are Google Advertising ID for Android and IDFA for iOS. These identifiers are required for tracking the conversions in most offers. To make sure your application receives offers and that those offers are tracked properly, it is important to verify that the device identifiers are available to Fyber. Device identifiers are the most commonly used values to track conversions in the advertising space. Please ensure that the GAID (Android) or IDFA (iOS) is being sent to the Fyber SDK on initialization.

The best ways to verify this:

  • Make sure DAU is measured within the Fyber dashboard. DAU tracking is based on those device identifiers - seeing the DAU in the Fyber dashboard means the identifiers are being received.
  • In the logging, make sure that the proper identifiers are being sent. You can do this by activating Fyber logging and looking for the URL that is sent to service.fyber.com/installs, which should contain the identifier, and will be used by our system for counting the DAU.
  • On Android you will want to look in the Logcat for the [FYB] tag, and in the call to service.sponsorpay.com, make sure that the “gaid” parameter is populated
  • On iOS you will want to look in the console logs for the [FYB Debug] tag, and in the call to service.fyber.com, make sure that the “idfa” parameter is populated.

Note: GAID & IDFA are gathered automatically during SDK start. When using Offer API, these values must be provided manually.

Offer Wall Integration Methods

The Offer Wall can be integrated either via our SDK or our Mobile Offer API. In each case there are some considerations for creating a good integration.

SDK Offer Wall

The SDK Offer Wall handles most things for you. Launching the Offer Wall is a single line of code, and can be done at any point after starting the SDK. We usually recommend launching it on request when a user interacts with some part of your UI, like a ‘Get Free Coins’ button.

You must send unique user ids. Under normal circumstances this would be the same identifier that you use within your game itself. We do not impose any format restrictions on the ids. If you do not have a unique user id to provide, you can pass null (or nil depending on the platform), and we will assign a unique id for you. Keep in mind that this is the same user id used for rewarding, so using our auto-generated ids generally means using our Virtual Currency Server (VCS) system as well.

Mobile Offer API

The API is somewhat more complicated, since you must do a lot of the work yourself. Launching the Offer Wall has the same flow but it’s the processing that is different.

Information: It is very important that you provide as much information as possible to the API. Even parameters that are labelled as optional should be filled in if at all possible. Lack of information can reduce the amount and even the quality of offers in the API response.

IP Address Our API will automatically detect the IP address that was used to generate the request to the API unless the ip parameter is passed with the request. It is possible to make API requests from a server and then send the information to a user’s device, but with this particular integration method it is important to use the ip parameter in the API request. Without it, you will serve broken offers to most of your users, since we will send offers according to the region of your server, and not that of the user.

Timing All API requests must be done in real time. You cannot cache the response a long time before the user navigates to the Offer Wall. Our inventory is constantly changing due to advertiser restrictions (impression caps, start and end dates, etc.) A request to the Offer Wall at one point in time can often return different results than it would even a few minutes later.

User IDs You must send unique user ids. Under normal circumstances this would be the same identifier that you use within your game itself. We do not impose any format restrictions on the ids.

Support Link The API response includes a support link that users can use to report broken offers to our customer support team. You should ensure that this link is presented to your users somewhere obvious in your interface.

Rewarded Video Integration Methods

Fyber has three recommended integration methods for Rewarded Video. We recommend the third style if you want the video button to always be seen by the user, and the first style if you want the button hidden unless there is a video available.

Standard Integration with User Initiated Requests

Method 1: The request is made when the screen with the placement on it is loading. A loading indicator is then placed on the button, or else the button is not visible until the request is complete. When the user taps the button, they go straight to the video.

  1. The user navigates to the screen with the placement on it
  2. A request for videos is made
  3. The screen with the placement on it loads with the video button either hidden or with a loading indicator on it. A common mistake here is to display a popup “No ads available” or even worse, “Error”.
  4. The request completes and either:
    • There is a video available and the button is activated
    • There is no video available and the button is deactivated
  5. The user taps on the video button
  6. The video is shown

After the video is complete, if the user is directed back to the screen with the video button, you should make another request for a video.

Method 2: The button is available as soon as the user navigates to the screen with the placement on it. When the user taps on the button, a video request is made, the user is presented with a loading screen, and then the video starts.

  1. The user navigates to the screen with the placement on it
  2. The user taps on the video button
  3. A request for videos is made
  4. A loading screen is shown to the user
  5. The request completes and either
  6. There is a video available and the video is shown
  7. There is no video available and the user is notified

A common mistake here is to display a popup “No ads available” or even worse, “Error”. We recommend “Please try again in a few seconds”. You do not want your users to think that the ads are “broken”. They might not try again if it sounds permanent.

Method 3: A hybrid of the other two. The request is made when the screen with the placement on it is loading. If the user taps the button before the request is complete, they see a loading screen until the request is complete, and then go to the video. If the user taps the button after the request is complete, they go straight to the video.

  1. The user navigates to the screen with the placement on it
  2. A request for videos is made
  3. The user taps on the video button and either
  4. If the request is incomplete, a loading screen is shown, and then either
    • There is a video available and the video is shown
    • There is no video available and the user is notified
  5. If the request is complete and there is a video, the user is sent to the video
  6. If the request is complete and there is no video, the user is notified

After the video is complete, if the user is directed back to the screen with the video button on it, you should make another request for a video.

Rescue Integration with Automatic Requests

Method 1: When a level is reliably shorter than five (5) minutes, a request can be made at the beginning of the level and the option to watch a video presented at the end of the level.

  1. The user begins the level and a request for videos is made
  2. Once the request is complete, the result is stored for later use
  3. The user completes the level (either successfully or not, depending on the context of the video option being presented) and the button to watch the video is displayed
  4. The user clicks on the button to watch the video and the video is launched
  5. When the video is complete, the user is given another chance to complete the level, or some other reward

Method 2: When a level is usually longer than five (5) minutes, a request should be made shortly before the level is over and the option to watch a video presented at the end of the level.

  1. The user begins the level and progresses through it
  2. At some point between 10 seconds and 5 minutes before the level can be expected to end (perhaps due to a level timer, or number of lives left), a request for videos is made
  3. When the user completes the level (either successfully or not, depending on the context of the video option being presented) then either
  4. If the end screen of the level is not yet visible, the result is stored for later use
  5. If the end screen of the level is visible, then either
    • The button to watch a video is disabled with a loading indicator until the request is complete
    • The button to watch a video is enabled immediately, and if the user taps on it before the request for videos is complete, then a loading indicator is shown
  6. The user clicks on the button to watch the video and the video is launched
  7. When the video is complete, the user is given another chance to complete the level, or some other reward

Interstitial Integration Methods

Method 1: Make a request when you want to display an interstitial to the user, show a loading indicator until the request is complete, and then display the interstitial.

  1. The user arrives at an interstitial placement
  2. A request for interstitials is made
  3. A loading indicator is displayed while the request is in progress
  4. When the request is complete, the loading indicator is dismissed and the interstitial is shown
  5. When the user dismisses the interstitial, the game resumes

Method 2: Make a request shortly before you want to display an interstitial to the user, and then display the interstitial when the user arrives at the placement.

  1. A request is made for interstitials shortly before the user arrives at an interstitial placement (but at least 5 seconds before)
  2. When the request is complete, the result is stored for later use
  3. The user arrives at an interstitial placement
  4. The interstitial is displayed to the user
  5. When the user dismisses the interstitial, the game resumes

Timing your requests

Finding the right time period to make the ad request is important to assure a better user flow and to make sure your user is getting their ad when they should. Some key factors:

  1. Ad Requests can take several seconds to complete In the worst case, our SDK will impose a timeout at 10 seconds. To make sure there is an ad available for display (impression), make the ad requests 10 seconds before you would like to show the ad.

Not requesting far enough in advance could result in users waiting too long for an ad and completely skipping the engagement opportunity. This could lead to reduced impressions.

  1. Making the requests too far in advance could lead to “expiration” of the ad Ads may have been pre-cached but the request was made too far in advance, resulting in ads no longer being available. This “expiration” could come from two different sources:
    • From the SDK / network side where the campaign that was precached on SDK initialization is no longer available to the user,
    • “Garbage collection” processes of the operating platforms that clear the pre-cached ad from memory (The mobile operation systems have processes that clean the memory to avoid memory overload.)

To avoid this, it is important to make sure you are making a new request each time the user approaches the desired ad placement, ideally 10 seconds in advance.

  1. Waiting for the SDK to complete initialization Make requests only after SDKs of all networks have finished initializing, especially in the case of mediation.

Making requests before all networks SDKs’ are finished initializing could lead to ads not being returned by the network, and in rare cases, technical issues.

Since not all networks notify Fyber when their SDK is finished initializing, it is not possible for us to notify your app when this is done. We recommend making requests for ads at least 15 seconds after the Fyber SDK start is called. As a reminder, we also recommend making the request closer to the time at which you’d like to display the ad to your user.

  1. Making too many consecutive requests Making numerous requests for ads in a short period of time serves no real benefit. The likelihood of inventory changing in the span of just a few seconds, or even minutes, is low. As such, you should always make only a single request shortly before presenting the user with the option to watch a video.

Fyber has also observed that making a significantly large number of requests that are never presented to the user can cause adverse side effects in all KPIs. Under normal circumstances, offers have daily limits to how many times they can be delivered. In order to ensure these limits are not breached, ads can be reserved for individual requests. If an ad is reserved for one request, that potential impression is not available for other requests. Making large numbers of consecutive requests without providing users with the opportunity to consume the offers returned by those requests can have the effect of locking down some number of impressions that would otherwise be available.

Demand Partner Reporting Credentials

Demand partner credentials can be tricky. Here are a few tips:

  • Configure all reporting APIs
  • Don’t reuse credentials
  • The first time a reporting API is activated, the Fyber system will pull in 30 days worth of revenue information for that demand partner
  • The Fyber system pulls revenue information from the reporting APIs every 6 hours for the revenue data of the past 7 days
  • The Fyber predictive algorithm uses data from the last 3 days for ranking mediation
  • If you configure a reporting API for credentials associated with a currently live integration, our system will pull in revenue associated with impressions that are not going through Fyber. This will result in skewed eCPMs for that demand partner.
  • Fyber ranks networks primarily on their eCPM, which means eCPM that is skewed by bad reporting API configurations will cause sub-optimal ranking.
  • Make sure server-side and API credentials match
  • If you change credentials, use manual eCPM for at least 3 days to ensure that the impression and revenue numbers match correctly before switching back to automatic eCPM.

Maximizing Conversion Rates for Demand Partners

Some demand partner networks are available for mediation through Fyber offer “Close” buttons on their videos. In order to make sure conversions are being tracked as well as ensure that your users receive their rewards after a complete view, we recommend disabling the “Close” button with ad networks who have these available. Please contact your Account Manager from each respective demand source to find out how to disable the “Close” button.

Streamlining the User Experience

When using Fyber Virtual Currency Servers (VCS) with Rewarded Video, either utilize the option provided by our SDK to request VCS automatically, or else wait 3-5 seconds after a video completes before requesting VCS.

When using VCS with Offer Wall, set the Offer Wall to be dismissed when the user returns to the app, and whenever the user navigates to a location in which they can see their total currency.

Fyber Dashboard Best Practices

Content Filters
Virtual Currency Exchange Rates
Do Not Block Cookies

Content Filters

The Content Filters manage the type of offers your app(s) will see from Fyber demand sources. This feature can be used to point to ads matching your userbase to your app, and allowing you to block ads you don’t want shown.

Content Filters also reduce diversity of ads your users can see. Reducing the number of potentially available offers will give the users less options to interact and will reduce monetization potential.

We recommended avoiding Content Filter use when not necessary. If you choose to use Content Filters, the number of offers from the Fyber exchange that your users can participate in is reduced.

Note: When integrating Fyber’s offer wall product for apps on iOS, we automatically create a filter to remove CPI campaigns from your offer wall. This is designed to comply with Apple’s policies.

Virtual Currency Exchange Rates

Make sure your virtual currency to real currency exchange rate is high enough to allow a good number of offers to display.

Your virtual currency exchange rate (essentially, a “price floor” for offers) determines how many virtual currency points to each real unit of currency is paid out on offer completions. If your virtual currency exchange rate is too low ($/€ 1 = 1 coin), then anything that pays lower than $/€ 1 will not equate to 1 coin and therefore will not display on your offer wall.

Note: Enabling rounding for your virtual currency exchange rate will round anything below 1 virtual currency point to 1 virtual currency point and allow for the display of more offers. Please consider the impact on your virtual economy when deciding whether to enable rounding.

Do Not Block Cookies

The Ad Control tab in your Fyber Dashboard allows you to set frequency caps and pacing for ads to optimize for user experience. In order for these features to work, you must pass in cookies.

For iOS specifically, please follow instructions here for working with Apple’s cookie accept policy.