iOS Ad Publishing

You can serve native, interstitial and banner ads very quickly and with little effort using Yahoo App Publishing and the Flurry SDK.

The following instructions apply to Flurry’s latest SDK 7.x.x.

About

The Flurry SDK provides you with an object-based API to create objects for Native, Interstitial and Banner ads. This means that you can use individual objects to control the lifecycle of an ad.

Sample Apps

  • Sample iOS code: for an Objective-C sample app with different banner, takeover and native ad types integrated, download, build, and run this app. Follow the guide for integration.
  • Yodel app for iOS: another Objective-C sample that shows different types of native ad placement, including vertical and horizontal streams of data interspersed with native ads.
  • Yodel Travels: a Swift sample that was made to demonstrate use of native stream and expandable ads by integrating them with content pulled from Tumblr.

Note

Flurry SDK requires minimum iOS6.

Native Ads Integration Code

Before you begin the native ad integration, you may wish to review the Native Ad Design Guidelines. The guidelines are intended to help you build engaging ad experiences while protecting the integrity of the advertisers’ brand assets. You need to adhere to these guidelines when implementing Yahoo Gemini native ads in your apps.

You may also wish to download, build and run the Flurry sample iOS app that serves native ads: Download the sample code and follow its README doc of content of this document for integration instructions.

To integrate Flurry Native Ads or Flurry Native Video Ads into your app, use the latest Flurry iOS SDK (native ads are available as of Flurry iOS SDK 6.0, native video ads are available as of Flurry iOS SDK 6.7).

Follow these steps:

Step 1. Configure the ad unit

Before you can integrate the code into your application, you need to configure the ad unit that your code references on the Flurry dev portal. For the native ads, the ad unit is configured as the “Stream” ad unit.

To enable native video ads, check the “Allow Video” box in the Ad Details section of Ad Unit configuration page. The current version of native ads supports static (image) and video ads. The video ads are mixed in with the static ads.


For all other ad unit placements, follow these detailed instructions on how to configure an ad unit: Basic Ad Unit Setup.

Note

that after you create a Stream ad unit on the dev portal, it takes about one hour for the ad unit to become active and to start serving the ads.

Important

Flurry recommends that for each UIViewController where the Native ads are served, you configure a single ad unit. This ad unit can be referenced multiple times in multiple locations within the same UIViewController. For example, if the native ad is placed in multiple cells of a table view, it references the same ad unit name. This ad unit can contain both image and video ads.

Integrating code for native ads requires fetching the ad assets and displaying the ad in a custom view that matches the application layout.

Step 2. Initialize the Flurry with the API key.

Step 3. Create the ad view to contain the ad assets.

Place this view within another view of your app. The same view can be used for both static and video ads.

See the corresponding view, as shown below:

native ad created

Step 4. Implement the FlurryAdNativeDelegate.

In the app code, implement the FlurryAdNativeDelegate to receive the callbacks related to the ad’s lifecycle events:

Step 5. Initialize the native ad.

To initialize the native ad assign the FlurryAdNativeDelegate and fetch the ad from Flurry. The Flurry server returns the ad’s assets and calls back adNativeDidFetchAd with the FlurryAdNative object reference:

You can create multiple native ad objects at the same time. The SDK keeps track of the fetch requests the app makes and adds the returned assets to their corresponding ad objects as they are made ready. The app can deallocate the native objects as it sees fit. Otherwise, they will be deallocated with the UIViewController that created them.

Step 6. Enable Native Ad Tracking

The Native ad needs to be registered for tracking by setting the trackingView property to the newly composed ad view. This step also enables the action associated with the user clicks onto the ad (i.e. the ad opens up another view as the result of the click). The trackingView property is set to the UIVIew that defines the ad.

If you plan to re-use the view to show different ads, call removeTrackingView() before setting the new ad tracking view.

Step 7. The ad is ready.

When the ad is ready, the native ad’s asset list will be available and can be accessed using the assetList property of the FlurryAdNative object. Note that this property returns an array of FlurryAdNativeAsset objects. The assets can then be used to populate a UIView within your app and can be used to display the native ad.

The video ads do not have an explicit asset name and asset value pair in the assetList. The video ads are identified with the isVideoAd property of the native ad object set to YES.

Step 8. Compose the view to display the ad.

To compose the view that displays the ad, parse the received assets list. Flurry recommends using AFNetworking library to assist while acquiring the image from the provided url. The link to AFNetworking installation instructions:

For example, the following code snippet demonstrates the process:

Flurry requires you, as the Publisher, to display the headline, advertiser name, one image and the branding logo. You can pick the image best suited for your requirements and crop the image to match your aspect ratio.

The potential assets and their key names are shown in the table below.

Name Type Description
summary STRING The call to action summary of the advertisement
headline STRING The Ad headline, typically a single line
source STRING The advertiser’s name
secBrandingLogo IMAGE The square image always present, size: 20 x 20px
secHqBrandingLogo IMAGE The square high-quality image of the sponsored logo. Currently, it is a starburst.png, always present, size: 40 x 40px
secOrigImg IMAGE The secured original image, size: 627px x 627px. Optional asset, not present for the video ads.
secHqImage IMAGE The secured high quality image, size: 1200px x 627px. Optional asset, not present for the video ads.
secImage IMAGE The secured image, size: 82px x 82px. Optional asset, not present for the video ads.
appCategory STRING The app category. Optional asset, present only for the app install ads and some video ads.
appRating STRING The app rating, expressed as 80/100 for the 4 star rating or 100/100 for the 5 star rating of the app. Optional asset, present only for the app install ads and some video ads.
secRatingImg IMAGE The secured image representing the number of the stars the app is rated with. Optional asset, present only for the app install ads and some video ads.
secHqRatingImg IMAGE The secured high-quality image representing the number of the stars the app is rated with. Optional asset, present only for the app install ads and some video ads.
showRating STRING true or false value recommending whether to show the star rating of the app or not. Optional asset, present only for the app install ads.
callToAction STRING The Call to Action string.
collapseImg IMAGE The secured image representing the collapse button used for composing the expandable ads.
expandImg IMAGE The secured image representing the expand button used for composing the expandable ads.

For all the assets whose type is Image, the value for the asset is a url string that links to the image. Note that the url points to either the local or remote resource:

  • Caching is enabled by default for the ad unit: The SDK caches the assets onto the device before it declares the ad ready. The asset’s url in FlurryAdNativeAsset points to the local file (url contains the locator in the form file:// ) where the asset resides. Ensure that you check the FlurryAdNative object’s ready property for an ad object’s readiness before preparing the view to display.
  • Caching is not enabled for the ad space: The assets are available via https url. Calling setImageWithURL on the FlurryAdNativeAsset object loads the assets directly from the network and does not cache the assets. This is an admin setting, set upon request.

Video Ads

The video ads do not have an explicit asset name and the video url is not exposed. Rather the video ads are identified with the isVideoAd property of native ad object set to YES.

The short Call To Action (CTA) string is provided in the asset list for all ads.

The Video ads are cached on the device by the default.

Note about Native Video Ads For the ad unit that are configured to receive video ads, each ad request returns either a video or a static (display) native ad. Other than rendering a native video ad, the integration steps for native video ads are the same as for native static ads.

To render a native video ad, you check if the ad returned is a video and and if so provide the view where the video is presented. In such a case, you must use FlurryAdNativeAsset#loadAssetIntoView().

Expandable Ads

Starting with the iOS SDK version 7.3.0, Flurry enables newer display format for native ads. You can choose to show the condensed ad view (also called Pencil ad format) with elements like title and summary. On tapping the ad, the ad view can be expanded to an elaborate view. This feature can be implemented by making use of the updated FlurryAdNative API and its updated FlurryAdNativeDelegate callbacks.

FlurryAdNative class has a new display state property with its enum values. The default value of the display state for the expandable ad is FLURRY_NATIVE_AD_EXPANDED. To indicate to the SDK that the ad is shown in the collapsed (pencil) view, the state value needs to be set to FLURRY_NATIVE_AD_COLLAPSED. Depending on the user’s interaction with the view, appropriate actions need to be taken as explained below.

Two new methods are added to help set the tracking view in the collapsed as well as in the expanded display state.

Normally native ads need to set the tracking view to the view that contains the ad’s assets.

For the expandable display, there are two new methods provided to set the tracking view referencing the expand button and the CTA button. When the ad is in the collapsed view, this view contains the expand button. Setting the setPencilViewToTrack on the collapsed ad allows the SDK to monitor for the user’s click on the expand button.

Similarly, when the ad is in the collapsed view, it contains the CTA button. Setting the setExpandedViewToTrack on the expanded view, allows the SDK to monitor for the user’s click on the CTA button.

The asset list contains the image assets for the expand and collapse buttons. The assets are named expandImg and collapseImg, respectively.

Note

The CTA view can’t be null. The CTA view in the condensed view can be used to launch the landing page, or it can be an invisible view to disable the feature.

By providing the CTA view, the end user can open the landing page without expanding the ad.

The expand button can’t be nil in either methods.

Setting the condensed view or the expanded view using the methods does not require you to set tracking view separately.

The expand button callbacks can be used to set the display state appropriately as follows:

Flurry SDK provides a delegate callback to notify the app when the display state is changed by either tapping on the condensed view or tapping the expand button. The FlurryAdNativeDelegate object can implement this delegate callback and respond appropriately as follows:

The above implementation only animates the table view’s height changes. You may add any changes that need to happen as the user taps on the ad related to change the size of the views.

Step 9. Build and run your code to see your ads displayed.

If you don’t see any ads, check the troubleshooting section in FAQs for iOS for tips.

Interstitial Ads Integration Code

Because every app is different, Flurry encourages you to experiment to find what works best for your needs.

Use Flurry Analytic to determine the places in your app with the highest user traffic. Typically, good placements include:

  • Games: On game launch, when a user completes a level
  • Social Networks: User completes an engagement (call, text, video)
  • Entertainment: User finishes consuming media (video, music)
  • Content & Media: User finishes consuming content
  • Utility: User finishes using tool

Flurry ad units represent unique placements in the app. If you app supports multiple ad placements, you can create multiple ad units.

To display full screen ads, video or static, follow these steps, adding these code snippets in your Xcode project:

  1. Initialize the Flurry system.
  1. Display the interstitial (takeover ad) in your app.
  1. To be notified of certain events during the full lifecycle of the interstitial ad, implement the FlurryAdInterstitialDelegate protocol and then assign it to the adInterstitial object you are working with.

The following callbacks may be of interest:


Important: Don’t set ad delegate to nil or remove ad in the viewWillDisappear or viewDidDisappear method of the presenting view controller that is passed into presentWithViewControler:. When a full screen ad is shown on the view controller passed into these routines, the viewWillDisappear and viewDidDisappear methods of this view controller are called.

  1. Run the app to see an Interstitial ad displayed. You should now see an ad similar to the following:

phone displayed images

If you are not seeing any ads, check the troubleshooting section in FAQs for iOS for tips.

Configure Ad Serving (Optional)

You can use a number of targeting parameters to modify the behavior of your ad units.

Beginning with version 6.x, Flurry SDK’s Object API supports ad targeting using an object of FlurryAdTargeting.

FlurryAdTargeting is a container for various properties to target an ad unit effectively such as:


The following table describes the targeting parameters supported for ad serving in SDK 6.x:

Parameters Description
testAdsEnabled Use this field to fetch test ads from the Flurry server during app development. Test ads won’t monetize and are provided for integration test only. Ensure that you set this to false before the app is launched.
location The user device location information can be attached to the FlurryAdTargeting object if the app has permission to do so. Once the app obtains permission, FlurryAd objects sends the location information to Flurry servers to support effective ad targeting.
userCookies UserCookies allow the app to specify information about a user executing an ad action. On ad click, a UserCookie key/value is transmitted to the Flurry servers. The UserCookie key/value pairs will be transmitted back to the developer via the app callback if one is set. This is useful for (server-side) rewarded inventory, to identify which of your users should be rewarded when a reward callback is sent.
keywords Keywords specify information about a user executing an ad action for the purposes of targeting. There is one keywords object that is transmitted to the Flurry servers on each ad request. If corresponding keywords are matched on the ad server, a subset of targeted ads will be delivered. Use keywords targeting to supply custom information tracked internally by your app.

Learn More

For detailed information on the Objective-C classes and methods available in the SDK, check out the API Reference documentation for iOS.