iOS SDK 9

Watch a video tutorial for integrating the iOS SDK.

Requirements

  • FairBid can be integrated in applications built with Xcode 8 with Bitcode disabled and Xcode 9 and above with Bitcode enabled
  • FairBid works on iOS 8 and above

Example App

To see a working iOS app that has each of the networks we support already integrated, check out our example iOS app on GitHub.

Step 1. Configure Dynamic Documentation

Select the version of the FairBid SDK you wish to view documentation for, and then select the networks you are integrating. The documentation on this page will update with specific instructions that may apply to your selections.

Network Selection:

Step 2. Download the SDK

The SDK includes FairBid, as well as wrappers for all 3rd-party networks.

SDK v9.50.0

Step 3. Add the SDK to your project

Unzip the downloaded file and drag and drop the HeyzapAds.framework to your project as well as any additional files. Make sure to have 'Copy Items' checked.

Add Framework to Xcode

Step 4. Add 3rd-party SDKs to your project

AdColony

AdMob

AppLovin

Chartboost

Domob

Facebook Audience Network

Fractional Media

Fyber Direct

HyprMX

InMobi

ironSource

Leadbolt

MoPub

Tapjoy

UnityAds

Vungle

If you haven't already, use our Integration Wizard to setup the 3rd-party networks you want to use with mediation.

The FairBid SDK will automatically detect and initialize the SDKs from 3rd-party networks. Some 3rd-party networks fail when initialized multiple times. Please do not initialize or otherwise directly interact with 3rd-party networks mediated by FairBid.

Step 5. Add User Consent

The General Data Protection Regulation requires you to scope your user's consent. A user is within the GDPR scope for your app when one or all of the following apply:

  • The user is currently located in the EU
  • The user has registered with the app as an EU resident
  • The app is specifically targeted to EU users

Once you have collected the user’s consent, you can pass it onto the SDK using the following API:

[HeyzapAds setGDPRConsent:userConsent];

userConsent should be Yes if you have the user’s consent, or No otherwise.

If you don’t pass the user’s consent to the SDK, only contextual ads will be shown to that user.

We recommend that the first time you gather the user’s consent, you pass it onto the SDK before starting the SDK. The SDK will then take the user’s consent into consideration when initializing. In the following sessions, you will only need to call the API if the user updates his or her consent.

Step 6. Configure your Xcode project

Import the following frameworks by pasting this code into your AppDelegate (you may need to enable modules in your Build Settings). (If you can't enable modules because you're e.g. using [Objective]-C++, add these frameworks to the Linked Frameworks and Libraries section in Xcode).

No additional configuration is needed for FairBid's SDK, but you may need to enable modules in your Build Settings. (If you can't enable modules because you're e.g. using [Objective]-C++, add these frameworks to the Linked Frameworks and Libraries section in Xcode).

From the General tab of your Xcode project's target settings page, link against these libraries:

Add Libraries

Also from the General tab of your Xcode project's target settings page, check the box labeled "Requires full screen" (this disables multitasking support, which needs to be disabled for ads to be able to set the orientation of their views):

Disable Multitasking

From the Build Settings tab of your Xcode project's target settings page, add the following to "Other Linker Flags":

Add Linker Flags

App Transport Security

iOS 9 added App Transport Security (ATS), which requires apps to use HTTPS for all networking. Starting in 2017, Apple will require that all apps use ATS unless they state a reason they can't.

All of the networks you have selected so far in the dynamic documentation (see the top of the page) fully support ATS, and do not require any additional configuration. Please ensure you've selected each network above that you will be integrating so this documentation can change if necessary.

Disable App Transport Security

iOS 9 added App Transport Security (ATS), which requires apps to use HTTPS for all networking. Starting in 2017, Apple will require that all apps use ATS unless they state a reason they can't.

Not all of your selected networks are ready for this requirement yet, so you'll need to add some exceptions. The following networks are requiring these exceptions:

Using an advertising SDK that needs to be excluded is considered a valid reason for needing this exception - in Apple's ATS docs, one acceptable reason is that your app must connect to a server managed by another entity that does not support secure connections. When your app is reviewed, you can provide this reason for needing the exceptions.

To add the necessary exceptions for the networks you chose, add the following entries to your app's Info.plist file:



Disable ATS

Register Custom URL Schemes

Starting in iOS 9, apps must register what URL schemes they can pass to [UIApplication canOpenURL:]. Add these URL schemes to your Info.plist:



Application URL Queries

Step 7. Initialize the SDK

In your application delegate's application:didFinishLaunchingWithOptions: method, start the FairBid SDK:

#import <HeyzapAds/HeyzapAds.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //    Demographic information about your app's current user can optionally be used to increase CPMs. If you have it, provide it at any time (but also as early as possible) like so:
    //    HZDemographics *demographics = [HeyzapAds demographicInformation];
    //    demographics.location = foo; // things like birthday, education, gender, and more can be set as well

    // Your Publisher ID is: 
    [HeyzapAds startWithPublisherID: @""];
    return YES;
}

Swift users need to import FairBid into the Bridging Header file. If you don't already have one, create a new Objective-C file in your project and Xcode will offer to generate one for you. Import FairBid into this file:

#import <HeyzapAds/HeyzapAds.h>

then start FairBid:

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    //    Demographic information about your app's current user can optionally be used to increase CPMs. If you have it, provide it at any time (but also as early as possible) like so:
    //    let demographics = HeyzapAds.demographicInformation()
    //    demographics.location = foo // things like birthday, education, gender, and more can be set as well

    // Your Publisher ID is: 
    HeyzapAds.startWithPublisherID("")

    return true
}

Step 8: Test your 3rd-Party Integrations (Optional)

The mediation SDK comes with a Mediation Test Suite that you can use to test each of the networks you've chosen:

The first screen lets you pick a network. Once you choose a network, you'll see if:

  1. The network is installed correctly.
  2. The network has valid credentials on your dashboard.
  3. The network is enabled on your dashboard.

From here, you can select a type of ad (Interstitial, Video, Incentivized, or Banner), fetch that ad, and then display it.

To use the Mediation Test Suite, simply call presentMediationDebugViewController after you start the SDK and have setup a root view controller:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [HeyzapAds startWithPublisherID: @""];

    // Create UIWindow
    // Set rootViewController

    [HeyzapAds presentMediationDebugViewController];
}
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    HeyzapAds.startWithPublisherID("")

    // Create UIWindow
    // Set rootViewController

    HeyzapAds.presentMediationDebugViewController()
    return true
}

At this point, you should launch the Mediation Test Suite and verify that each network you want to use has the correct credentials and shows ads correctly.

Step 9. Show Ads

Methods you call on the FairBid SDK will automatically dispatch to your enabled 3rd-party SDKs; a call to showAd will iterate over ad networks in order of expected CPM until it finds one that has an ad, optimizing CPM and fill rate. Use the code below to display your preferred ad format:

Interstitial Ads

While you can call fetch for interstitial ads manually without causing any harm, our SDK will automatically try to fetch for the default tag when the SDK starts, and also after every ad shows, by default.

// Interstitial Ads are automatically fetched from our server by default on SDK start and after an ad shows
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZInterstitialAd showWithOptions:options];
// Interstitial Ads are automatically fetched from our server by default on SDK start and after an ad shows
let options = HZShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
HZInterstitialAd.showWithOptions(options)

Video Ads

As early as possible after starting the SDK, call fetch to fetch a video ad if your app will use them. You must do this because videos are not fetched automatically when the SDK is started, unlike our interstitial ads. However, video ads will autofetch after being shown the first time as long as autofetching is left enabled (see our Advanced docs for more about autofetching).

// As early as possible after starting the SDK, call fetch
[HZVideoAd fetch];
// As early as possible after starting the SDK, call fetch
HZVideoAd.fetch()
// Later, such as after a level is completed
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZVideoAd showWithOptions:options];
// Later, such as after a level is completed
let options = HZShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
HZVideoAd.showWithOptions(options)

Rewarded Video Ads

As early as possible after starting the SDK, call fetch to fetch a rewarded video ad if your app will use them. You must do this because rewarded videos are not fetched automatically when the SDK is started, unlike our interstitial ads. However, rewarded video ads will autofetch after being shown the first time as long as autofetching is left enabled (see our Advanced docs for more about autofetching).

// As early as possible after starting the SDK, call fetch
[HZIncentivizedAd fetch];
// As early as possible after starting the SDK, call fetch
HZIncentivizedAd.fetch()
// Later, such as after a level is completed
HZShowOptions *options = [[HZShowOptions alloc] init];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
[HZIncentivizedAd showWithOptions:options];
// Later, such as after a level is completed
let options = HZShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
HZIncentivizedAd.showWithOptions(options)

Banner Ads

FairBid offers banner ads through its in-house network, Fyber Exchange. We also mediate banners from AdMob, Facebook Audience Network, Mopub, and InMobi.

Note: Most banner networks have a setting on their dashboard to automatically refresh at a given time interval. If you want to use this feature, it is strongly recommended that you use the same time interval on all of the banner networks you are using. Different refresh rates for different networks can result in confusing impression statistics.

HZBannerAdOptions *options = [[HZBannerAdOptions alloc] init];
[HZBannerAd placeBannerInView:self.view
            position:HZBannerPositionBottom
            options:options
            success:^(HZBannerAd *banner) {

            }
            failure:^(NSError *error) {
              NSLog(@"Error = %@",error);
            }
];
let options = HZBannerAdOptions()
HZBannerAd.placeBannerInView(self.view, position: HZBannerPosition.Bottom, options:options, success: {
      (banner) in
    }, failure: {
      (error) in println("Error is \(error)")
    }
)

For details on configuring the sizes of banners, more customizable placement of banners, callbacks, and more, please see our Banners Guide. Our Objective-C API documentation also covers this information.

Offer Wall Ads

The FairBid SDK provides access to the Fyber Offer Wall as of SDK version 9.12.0. The Offer Wall allows your users to complete certain activities in exchange for in-game currency.

Fetch

To fetch an Offer Wall ad:

[HZOfferWallAd fetch];
HZOfferWallAd.fetch()

Show

To show an Offer Wall ad:

HZOfferWallShowOptions *options = [HZOfferWallShowOptions new];
options.viewController = self; // Only necessary if you're using multiple view controllers in your app
options.shouldCloseAfterFirstClick = YES; // auto-close after first offer interaction?
options.animatePresentation = YES;

[HZOfferWallAd showWithOptions:options];
let options = HZOfferWallShowOptions()
options.viewController = self // Only necessary if you're using multiple view controllers in your app
options.shouldCloseAfterFirstClick = YES // auto-close after first offer interaction?
options.animatePresentation = YES

HZOfferWallAd.showWithOptions(options)

See our detailed Offer Wall docs for more code examples on how to reward the user for offer wall interactions.

All good? Head over to your mediation dashboard to view revenue, impressions, eCPM, network credentials, and more.


More Information:

To learn more about Native Ads, click here.
To view an Example App, click here.
To go to basic iOS SDK setup, click here.
To view Advanced Features, click here.