Unified Platform – iOS

Our Unified Platform with Fyber, also called SDK 10 or the Fyber Wrapper, brings together the core features of Heyzap and Fyber into a single SDK. Things like Offer Wall and Fyber's different selection of ad networks are offered via this wrapper SDK.

Native ads, Heyzap Cross Promotion, and some of our dashboard's more powerful features & settings (e.g.: Segmentation, most uses of Tags, and some of the Publisher Settings) are not supported via this wrapper SDK, so consider what features you will be using when deciding which SDK to use.

From an integration perspective, the only major change when switching to the Unified Platform is the replacement of "raw" third-party network SDKs with Fyber's adapter bundles. Each of Fyber's adapter bundles contains its own code along with the third-party SDK, so you must use these instead.

Requirements

  • The Heyzap/Fyber Unified Platform works on iOS 6.0 and above.
  • In order to download and use SDK 10, you must first have a payout method selected & filled out here.

Step 1. Configure Dynamic Documentation

Select the networks and app 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

SDK v10.4.1

By use of the Heyzap SDK you agree to our Heyzap SDK Agreement

Using Xcode 6? Download our Xcode 6 compatible SDK and adapters here, then follow the instructions in Native-iOS-README.md.

Step 3. Add the SDK to your project

Switching from SDK 9? Start by deleting your old Heyzap SDK, and all 3rd-party ads SDKs.

Unzip the downloaded file to get our iOS library. Drag both the HeyzapAds.framework and FYBHZMediationTestSuite.embeddedframework into Xcode, making sure that "Copy items" and "Create groups" are checked.

Add Framework to Xcode

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

AdColony

AdMob

Apple iAd

AppLovin

Chartboost

Facebook Audience Network

HyprMX

InMobi

Tapjoy

UnityAds

Vungle

Step 5. 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):

No additional configuration is needed for Heyzap's SDK, but you may need you may need to enable modules in your Build Settings.

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

Bitcode

Bitcode is a new feature added in Xcode 7 to compile apps to LLVM Bitcode instead of directly to CPU code (armv7, armv7s, arm64). Using Bitcode will give you smaller app binary sizes and is required for tvOS and watchOS apps. Unfortunately, these networks you've selected don't support Bitcode yet, so you'll have to disable it:

To disable it, find the "Enable Bitcode" setting in your Xcode target's Build Settings, then set it to "No".

Step 6. Initialize the SDK

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

#import <HeyzapAds/HeyzapAds.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Your Publisher ID is: 
    [HeyzapAds startWithPublisherID: @""];
    return YES;
}

Swift users need to import Heyzap 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 Heyzap into this file:

#import <HeyzapAds/HeyzapAds.h>

then start Heyzap:

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    // Your Publisher ID is: 
    HeyzapAds.startWithPublisherID("")

    return true
}

Step 7: 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. From the secondary screen, you can select a type of ad (Interstitial, Incentivized, or Banner), fetch that ad, and then display it.

To use the Mediation Test Suite, simply call [HeyzapAds 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()
}

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 8. Show Ads

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

Version 9 of the Heyzap SDK included an API that could be used to display only interstitial video ads. The unified platform's server-side configuration options have made this API redundant, and it has been removed. If you would like to display only video ads, please use the HZInterstitialAd API, and set your game's "Blended Video" option to "Enabled: show ONLY video". This option can be found under "Publisher Settings" for your game.

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

HZBannerAdOptions *bannerOpts = [[HZBannerAdOptions alloc] init];
bannerOpts.presentingViewController = self; // Only necessary if you're using multiple view controllers in your app
[[HZBannerAdController sharedInstance] placeBannerAtPosition:HZBannerPositionTop options:bannerOpts success:^(UIView *banner) {
    NSLog(@"Showed banner");
} failure:^(NSError *error) {
    NSLog(@"Error showing banner: %@",error);
}];
let options = HZBannerAdOptions()
bannerOpts.presentingViewController = self // Only necessary if you're using multiple view controllers in your app
HZBannerAdController.sharedInstance().placeBannerAtPosition(HZBannerPosition.Top, options:options,
  success: {
    (banner) in
  }, failure: {
    (error) in print("Error is \(error)")
  }                                                        }
)

Offer Wall

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

To show an Offer Wall ad:

// Create an instance of the FYBOfferWallViewController
FYBOfferWallViewController *offerWallViewController = [HeyzapAds offerWallViewController];
offerWallViewController.shouldDismissOnRedirect = YES; // set this if you want the Offer Wall to close itself after the user interacts with one offer

// Show the Offer Wall
[offerWallViewController presentFromViewController:self animated:YES completion:^{
    // Code executed when the Offer Wall is presented
} dismiss:^(NSError *error) {
    // Code executed when the Offer Wall is dismissed
}];

To track validated rewards via Fyber's Virtual Currency Server:

// Get the Virtual Currency Client
FYBVirtualCurrencyClient *virtualCurrencyClient = [HeyzapAds virtualCurrencyClient];

// self should conform to the FYBVirtualCurrencyClientDelegate protocol
virtualCurrencyClient.delegate = self;

// Request the delta of coins
[virtualCurrencyClient requestDeltaOfCoins];

The delegate methods, from FYBVirtualCurrencyClientDelegate, that you should implement:

// Reward your user `response.deltaOfCoins` amount of virtual currency, because an offer they previously completed was validated
- (void)virtualCurrencyClient:(FYBVirtualCurrencyClient *)client didReceiveResponse:(FYBVirtualCurrencyResponse *)response {
    NSLog(@"Received %.2f %@ (currency id: %@)", response.deltaOfCoins, response.currencyName, response.currencyId);
}

- (void)virtualCurrencyClient:(FYBVirtualCurrencyClient *)client didFailWithError:(NSError *)error {
    NSLog(@"FYBVirtualCurrencyClient error: %@", error);
}

You will need to call the requestDeltaOfCoins method periodically to check for validated offers. Offers are validated server-side and can take any amount of time, depending on the offer.

Fyber's docs have more advanced information on configuring the Offer Wall if you are interested.