Native Ads¶
Important
We want you to know that all iOS Flurry SDKs are fully compliant with ATS since version 7.2.0 released September 2015. Flurry does not require any special exceptions to be added to your apps.
Note
Check out our video tutorial on integrating native stream ads in Swift.
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).
Integrating code for native ads requires fetching the ad assets and displaying the ad in a custom view that matches the application layout.
The steps to perform native ad integration are described in the following sections.
Before You Begin¶
Review the Native Ad Design Guidelines: These guidelines are intended to help you build engaging ad experiences while protecting the integrity of the your brand assets. You need to adhere to these guidelines when implementing Yahoo Gemini native ads in your apps.
Download our Sample Apps: We’ve created sample apps in Objective-C and Swift to exemplify the best practices when integrating Native ads:
Objective-C: Download the sample code and follow the steps in the README doc for integration instructions.
Swift: Download the sample code and follow the steps in the README doc for integration instructions.
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 the 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
Once 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.
Step 2. Initialize 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:
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¶
A 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 the AFNetworking library to assist while acquiring the image from the provided url. The link to AFNetworking installation instructions:
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 theFlurryAdNativeAsset
object loads the assets directly from the network and does not cache the assets. This is an admin setting, set upon request.
Video Ads¶
Video ads do not have an explicit asset name and the video url is not exposed. Rather, video ads are identified with the isVideoAd
property of the native ad object set to YES
.
The short Call To Action (CTA) string is provided in the asset list for all ads.
Video ads are cached on the device by the default.
Note
For the ad unit that is 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, check if the ad returned is a video, and if so, provide the view where the video is presented. In such a case, you must use FlurryAdNativeAsset#loadAssetIntoView()
.
Expandable Ads¶
Starting with iOS SDK version 7.3.0, Flurry enables newer display formats for native ads.
You can choose to display 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 the 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.
Learn More¶
For detailed information on the Objective-C classes and methods available in the SDK, check out the API Reference documentation for iOS.