iOS SDK - Native Ads

These docs are for Heyzap Native Ads only, not mediated native ads.

Heyzap Native Ads allow you to seamlessly embed ads into your application, improving user experience and enabling greater flexibility for game developers.

Overview

Three classes are used for native ads:

  • HZNativeAdController: Responsible for fetching native ads from our server. If the fetch is successful, it returns an HZNativeAdCollection in a completion block.
  • HZNativeAdCollection: A thin wrapper around an NSArray of HZNativeAds. You can access the array through its ads property.
  • HZNativeAd: A model representing a single ad. HZNativeAd includes properties like the game's name and icon URL, among other features of the game.
  • HZNativeAdImage: A model representing an image. It includes properties like the URL of the image and its size.

Step 1. Integrate the SDK

Follow our documentation for instructions on integrating the SDK.

Step 2. Fetch and Show Native Ads

To fetch any number of ads, call fetchAds:tag:completion: with the maximum number of ads you want to fetch. Note that even if you're displaying ads one at a time, you should fetch a large number of ads and work through that list (this reduces network requests and ensures you won't get duplicate ads).

[HZNativeAdController fetchAds:20 tag:nil completion:^(NSError *error, HZNativeAdCollection *collection) {
    if (error) {
        NSLog(@"error = %@",error);
    } else {
        // Use the `collection` to display ads
    }
}];
HZNativeAdController.fetchAds(10, tag: nil) { (error, collection) -> Void in
    if (error == nil) {
        // Handle error
    } else {
        // Use the `collection` to display ads
    }
}

Access an HZNativeAd from the collection, and use its properties to embed an ad into your application:

HZNativeAd *ad = collection.firstObject; // The collection is guaranteed to have atleast one ad.
gameNameLabel.text = ad.appName;
gameIconView.imageURL = ad.iconURL;
starRatingWidget.stars = ad.rating;
let ad: HZNativeAd = collection.ads.first! as HZNativeAd // The collection is guaranteed to have atleast one ad.
gameNameLabel.text = ad.appName
gameIconView.imageURL = ad.iconURL
starRatingWidget.stars = ad.rating

HZNativeAd provides several properties you can use to create an ad, including:

  • appName: The advertised app's name
  • iconURL: The URL of the app's icon. Images are 256x256 PNGs, but not all images will have pre-rounded corners (you'll need to apply a mask or corner radius yourself).
  • landscapeCreative: An instance of HZNativeAdImage that has properties for displaying a large, landscape creative for the app.
  • portraitCreative: An instance of HZNativeAdImage that has properties for displaying a large, portrait creative for the app.
  • rating: The app's App Store rating
  • category: The category of the app in the App Store (e.g. "Role Playing")
  • appDescription: The App Store description of the app
  • developerName: The developer of the app
  • rawResponse: An NSDictionary containing the raw JSON response from our server. You can use this dictionary to access new properties Heyzap might add without updating the SDK.

Step 3. Report Impressions

If you're showing a list of ads together—in a UITableView for example—you can report an impression for all of them using the HZNativeAdCollection object:

[collection reportImpressionOnAllAds];
collection.reportImpressionOnAllAds()

Conversely, if you're displaying ads one at a time, you can report an impression for a single ad:

[nativeAd reportImpression];
nativeAd.reportImpression()

Step 4. Report Clicks and Display the App Store

Once the user clicks an ad, you can display the App Store for the advertised game from a UIViewController. You must call this method for Heyzap to correctly track installs:

// Optionally, display a loading spinner here.
[nativeAd presentAppStoreFromViewController:self
                              storeDelegate:self
                                 completion:^(BOOL result, NSError *error) {
    // Dismiss the loading spinner here, if you showed one.
    // Apple's SKStoreProductViewController may error out trying to load the app store; you can ignore this error as we fallback to switching to the app store app in this case.
}];
// Optionally, display a loading spinner here.
ad.presentAppStoreFromViewController(self, storeDelegate: self, completion: { (result, error) -> Void in
    // Dismiss the loading spinner here, if you showed one.
    // Apple's SKStoreProductViewController may error out trying to load the app store; you can ignore this error as we fallback to switching to the app store app in this case.
})

You must pass a delegate object which responds to the SKStoreProductViewControllerDelegate method productViewControllerDidFinish:. Typically, you'll just dismiss the view controller in this method:

- (void)productViewControllerDidFinish:(SKStoreProductViewController *)viewController {
    [self dismissViewControllerAnimated:YES completion:nil];
}
func productViewControllerDidFinish(viewController: SKStoreProductViewController!) {
        self.dismissViewControllerAnimated(true, completion: nil)
    }

API Documentation

For complete, API-level documentation, refer to our header files in Xcode or see the Cocoadocs.