iOS SDK Integration Manual

1. Overview

This manual shows how to integrate and setup YieldloveAdIntegration in your iOS app.

Find the CMP integration manual here: https://stroeerdigitalgroup.atlassian.net/wiki/spaces/SDGPUBLIC/pages/2408022033/iOS+CMP

2. Before you start

Receive an APPLICATION_NAME (to be set only once) and a PUBLISHER_CALL_STRING (represents the ad slot). Please contact your account manager at Ströer to get the APPLICATION_NAME and PUBLISHER_CALL_STRING. You will need to pass these two identifiers when requesting an ad using the SDK.

3. Try out our example app

We invite you to take a look at example app. It already contains test configuration, so you can try it even before receiving APPLICATION_NAME and PUBLISHER_CALL_STRING.

Example app can also clarify some implementation details. It is also possible to change settings of the app (as shown in app's README) and run it with your own configuration, after you receive it.

4. Adding SDK to your project

4.1. Cocoapods integration

The ad integration package is distributed as a “Pod”. Follow the instructions to install CocoaPods into your app. Afterwards the SDK dependency can be integrated.

Update repository

Edit your Podfile so that SDK is included as a dependency.

Include SDK pod

Then run

Install SDK

Note: Our modules, alongside with other dependencies, may require you to use minimum targeted iOS version 11.0 or higher.

5. Implementation

5.1. Setup

Before requesting an ad, you need to call Yieldlove.setup(appName:). This needs to be done only once. For example, in main application initializer.

Set application name

Note on caching: SDK relies on an external configuration to serve ads. Once the app requests the first ad with a certain app name, the configuration is cached on the user’s phone to reduce the number of http requests. It will refresh after a time limit specified in the config itself. During the integration, bear in mind you might need to reinstall the app after using a different appName to wipe configuration that is already downloaded.

5.2. Testing configuration

Use this configuration to start implementation even before receiving own configuration:

• App name: appDfpTest

• Banner ad slot: banner

• Large banner ad slot: banner?large

• Interstitial ad slot: interstitial

• Rewarded ad slot: rewarded

5.3. Request a banner ad

5.3.1. Request a banner ad in Swift

Replace PUBLISHER_CALL_STRING placeholder.

Request a banner

Now implement YLBannerViewDelegate like this:

Delegate implementation

5.3.2. Request a banner ad in Objective-C

Request a banner from ObjC

5.3.3. Resizing banner ads

Sometimes ads received through Prebid are not properly resized. This issue is documented on the Prebid website.

To overcome this, we recommend that app developers call the Yieldlove.instance.resizeBanner(banner: YLBannerView) function on all banner ads the app serves using the SDK. This function needs to be called after the banner ad has been added to a view.

Resize function is asynchronous. If you need a notification when it completes, pass a completion handler to resizeBanner(banner: YLBannerView, handler: @escaping () -> Void).

5.4. Request an interstitial

5.4.1. Request an interstitial in Swift

Use the following code to show an interstitial. Replace PUBLISHER_CALL_STRING placeholder.

Request an interstitial

To receive notifications about presentation of the interstitial ad, implement GADFullScreenContentDelegate protocol.

This method accepts a third optional parameter, a GAMRequest, useful to pass information like contentURL

5.4.2. Request an interstitial in Objective-C

Request an interstitial from ObjC

This method accepts a third optional parameter, a GAMRequest, useful to pass information like contentURL

5.5. Memory Management

SDK keeps a weak reference to the YLBannerViewDelegate object that app developers pass with ad request. This allows the developer not only to release resources when ad is not needed anymore, but also acts as a signal to the SDK to do internal cleanup.

When YLBannerViewDelegate reference becomes nil, the SDK will:

• release all objects associated with this ad

• stop refreshing the banner in case of auto-refreshable banners

App developers need to clear all strong references inside the app to the YLBannerViewDelegate object passed with ad request after the ad is not needed anymore. This typically requires that app developer decouples YLBannerViewDelegate implementation from UIView or ViewController.

Alternatively, clear the delegate from the bannerView after the ad is not needed anymore. This will have the same effect.

Release delegate

To reiterate, if your app:

• Keeps one or more strong references to the YLBannerViewDelegate object that it passed with ad request

OR

• Never clears the delegate from the ads that it serves

then it is impossible for SDK to perform cleanup and as a result, Swift ARC will not remove objects from memory. This means that over time, as the app serves more ads, memory usage will go up significantly. This may lead to performance problems and app being terminated by iOS.

5.6. Auto-refreshable Banners

SDK supports auto-refreshable ad slots. Ad slots are not auto-refreshable by default. Usually only a couple ad slots are configured as auto-refreshable.

Auto-refreshable ad slots will reload an ad after a configured time interval. Publishers need to take a couple more steps to implement auto-refreshable ad slots in addition to normal ad slots.

When banner is reloaded, SDK will call the same delegate method:

Since ad is reloaded into the same GADBannerView which is already added to the app view, publisher should not add the ad to the view again.

We provide bannerView.wasBannerRefreshed() function to let publishers know if ad was reloaded.

Only add banner to view once

If two or more refreshable ad slots with the same ad slot id are placed in the view at the same time, only one of them will be refreshed.

IMPORTANT:

When implementing auto-refreshable ad slots it is crucial to signal to the SDK that ad is no longer in view. SDK will then stop the auto-refreshing. We recommend to set ad delegate to nil when ad is no longer needed. See chapter 5.5. Memory Management for details.

If app does not signal to the SDK that auto-refreshable ad is no longer needed, it will lead to unnecessary ad requests being made in background, reducing performance of the app, consuming battery and mobile data.

5.7. Rewarded ads

5.7.1. Request a rewarded ad in Swift

Use the following code to show a rewarded ad. Replace PUBLISHER_CALL_STRING placeholder.

Request a rewarded ad

To receive notifications about rewarded ad, implement GADFullScreenContentDelegate protocol.

This method accepts a third optional parameter, a GAMRequest, useful to pass information like contentURL

5.7.2. Request a rewarded ad in Objective-C

Request a rewarded ad from ObjC

This method accepts a third optional parameter, a GAMRequest, useful to pass information like contentURL

6. Banner Ad Sizes

There are two ways of setting up ad unit sizes. In a 1:1 relation every ad unit is given a single size. All banners served by requesting this ad unit will have the same size. In 1:N relation ad unit may have more than one size. In this case banners may have different sizes. Depending on the setup, a different method should be used to get banner sizes.

6.1. One-to-one relation

Advantage of this setup is that ad sizes are known in advance.

To get banner ad sizes for ad slot use the following API method:

Get ad sizes

Example in Swift:

Get ad sizes callback

Or in Objective-C:

Get ad sizes from ObjC

6.2. One-to-many relation

Under this approach the sizes are determined after ad response. It is important to read the sizes after the resize function has returned.

To get banner ad sizes for ad slot use the following code in YLBannerViewDelegate implementation:

Get ad sizes in 1:N

7. Targeting (recommended)

The following targeting is supported:

• Key-Value Targeting (sometimes called Custom targeting)

• Category exclusions

• Content URL

• Publisher provided identifiers

• Keywords

We recommend to set contextual targeting parameters. Especially in cases where the user has not given consent in the CMP or ATT (iOS), we see better monetization if, for example, the content URL is available in the ad request.

7.1. Targeting on Global Level

Targeting for ad requests can be set on a global level. That means that when a property is set, it is set for all ad requests. Set the targeting as early as possible in your app's lifecycle to make sure every request contains desired targeting.

Set custom targeting

Yieldlove.instance.adRequest is an instance of GAMRequest, so set any properties you would set on this object, like contentURL, publisherProvidedID, etc.

7.2. Targeting per Ad Request

Implement getGAMRequest() method of YLBannerViewDelegate. Return a GAMRequest from this method that contains your desired targeting. This is the same delegate that you will pass as an argument when making an ad request with the SDK.

Supply other properties with request

For interstitials please pass a GAMRequest as third optional argument to the ad call.

Passing contentURL to an interstitial request

Passing custom key-values to an interstitial request

How this works Before SDK makes an ad request it calls this method, takes the targeting that you pass, and applies it to the request. Values passed through this method have higher priority than properties of same name that are set on global level. Values set on global level will be overridden by values passed through this method, unless it is possible to combine them (for example, in case of dictionaries).

7.3. Prebid Targeting Parameters

The SDK integrates Prebid Mobile for header bidding. Prebid Mobile supports global targeting parameters. See the list of parameters on Prebid Mobile website.. Targeting parameters are set once and apply to all Prebid ad requests. They do not change during a given user session.

Because Prebid Mobile’s targeting is a global object, you can use it to set the targeting parameters directly. For example, set context keywords like this:

Prebid targeting

Note: As part of the initial integration, we already set the iTunesID and storeURL for your app. So both fields do not need to be transferred additionally by you. However, please make sure to inform us in case of changes.

7.4. Contextual Targeting

If supplied, SDK forwards contentURL and IDFA with each ad request (banner and interstitials) to TheAdex for purposes of contextual targeting.

For this to happen:

• access to IDFA needs to be granted by end user of publisher’s app

• publishers supplies contentURL with GAMRequest object passed through delegate

8. Debug Info Panel

Hold three fingers on an ad for a couple seconds and then let go to enter ad debugging mode. In ad debugging mode SDK displays a debug info label in top left corner of a banner. Tap a label to bring up a panel with debugging information about an ad. Double tap the panel anywhere to copy the displayed text.

Alternatively, programmatically set Yieldlove.instance.developerModeEnabled to true. This flag is meant for ad debugging purposes. Do not set this flag by default in builds which you intend to submit to App Store.

Changelog

9.5.0 (28.11.2023)

PromiseKit versions synchronized across all modules, prebid-mobile-ios dependency updated.

9.4.3 (28.8.2023)

Maintenance release, provide GAM Ad Unit in bid request.

9.4.1 (16.5.2023)

Reduce the time needed to hold an ad to show debug panel.

9.4.0 (9.5.2023)

Introduce debug info panel.

9.3.0 (4.10.2022)

Add support for rewarded ads. See chapter 5.7. Rewarded ads

9.0.2 (13.9.2022)

Fixed issue with notifying delegate on refresh

9.0.1 (19.8.2022)

Internal changes

9.0.0 (15.8.2022)

Change Adex consent check

8.2.3 (11.8.2022)

Fix a bug that contributed to inefficient memory usage

8.2.2 (10.8.2022)

Internal refactoring

8.2.1 (3.8.2022)

Fix a bug that sometimes prevented the refresh timer in auto-refreshable banners from being stopped

8.1.1 (27.7.2022)

Add support for auto-refreshable banners

8.0.0 (13.7.2022)

Update Google Ads Mobile SDK to 9.7.0

7.8.0 (1.7.2022)

Add clear configuration cache method

7.7.0 (20.6.2022)

Update prebid-mobile to 2.0.1

v7.6.1 (13.6.2022)

Internal changes: set Open Measurement partner/version

v7.5.0 (13.6.2022)

Remove Alamofire dependency

v7.4.0 (20.5.2022)

Solve compiler version warning

v7.3.3 (18.5.2022)

Fix adding of supported mraid version for Prebid interstitial

v7.2.0 (2.5.2022)

• Internal refactoring

• Remote monitoring (disabled for now)

v7.1.14 (2.5.2022)

Fix a bug where publishers were not able to build apps built to physical phones ("The code signature version is no longer supported" error)

• Set CriteoPublisherSDK to "Do not embed"

• Add -ObjC to Other Linker Flags

v7.1.13 (26.4.2022)

Internal refactoring

v7.1.12 (5.4.2022)

Do not send empty contentUrl

v7.1.9 (16.3.2022)

Brings compatibility with Swift compiler version 5.6 (Xcode 13.3). Works together with YieldloveConsent version 4.6.3

v7.1.6 (28.2.2022)

Drop back to iOS 11 as minimum required iOS version

v7.1.5 (24.2.2022)

Fix a bug where empty consent string would cause String index is out of bounds error.

v7.1.4 (9.2.2022)

Fix a bug which caused a single ad to be shown in view at the time.

v7.1.3 (1.2.2022)

Internal changes:

• Config structure changed for openRtb apis

v7.1.1 (26.1.2022)

Internal changes:

• SDK now sends MRAID_1, 2 and 3 signals to Prebid server when configured in External Configuration.

v7.0.0 (24.1.2022)

Add Criteo as a source of ads.

API breaking changes:

• Argument labels changed to lowercase in API method signature bannerAd(adSlotId:, viewController:, delegate:). Previous labels were: AdSlotId, UIViewController, Delegate

• API method Yieldlove.instance.setAppName(appName:) was replaced by Yieldlove.setup(appName:)

• No longer possible to manually deallocate ads by calling deallocate() on Deallocator objects. Deallocation happens automatically during next ad request

v6.3.0 (21.1.2022)

Internal changes:

• SDK now sends idfv and atts in requests to Prebid server

v6.2.0 (20.1.2022)

Internal changes:

• SDK now sends additional headers with bid requests to Prebid server

v6.1.0 (25.11.2021)

Update to the latest Google Mobile Ads SDK, version 8.13.0
Update Carthage installation information

v6.0.2 (1.11.2021)

Make Carthage package usable with Xcode 13

v6.0.1 (29.10.2021)

Remove the need to change imports to import YieldlovePrebidMobile if publisher uses PrebidMobile in app code, for example to set some targeting. Now it is possible to keep existing import PrebidMobile declaration.

This release also brings Carthage package, which did not get released for 6.0.0.

v6.0.0 (27.10.2021)

Pass Content-Url to header bidding requests in addition to GAM ad requests. If Content-Url is provided by publisher, SDK will now also forward it to Prebid server to bring better targeting.

This release uses a customized version of Prebid Mobile SDK. If you are importing PrebidMobile in your code, for example to set some targeting, please change your imports to import YieldlovePrebidMobile.

v5.7.5 (11.10.2021)

Updated podspec to match requirements for dependencies.

v5.7.1 (6.10.2021)

Fix Carthage module. Apps are now required to target iOS 11.

v5.7.0 (20.9.2021)

Upgrade Prebid to 1.12.0

v5.6.0 (25.8.2021)

Add remote error logging

v5.5.0 (17.8.2021)

Added SDK version logging

v5.4.0 (9.8.2021)

Upgrade Alamofire to v5

v5.3.2 (23.7.2021)

Maintenance release after changing internal project structure

v5.3.1 (19.7.2021)

Fixed a bug where SDK would call Prebid even if rtaAuction was set to false for an ad slot in external configuration.

v5.3.0 (16.7.2021)

SDK provider can now define iTunesID property per app in configuration. SDK will pick up this property and pass it as a targeting parameter to Prebid server.

v5.2.1 (16.7.2021)

Fixed a bug where SDK would not pass StoreURL with interstitial requests.

v5.2.0 (14.7.2021)

SDK provider can now define StoreURL property per app in configuration. SDK will pick up this property and pass it as a targeting parameter to Prebid server.

v5.1.1 (7.7.2021)

Fixed 3rd party SDK dependencies to a specific minor version in Podspec. Publishers are no longer able to jump minor versions of 3rd party dependencies of the SDK. Publishers can still update to newer bugfix versions of 3rd party dependencies of the SDK.

Before:

This meant that publishers could install Google SDK 8.3.2 but also 8.7.0, and all the versions up to, but not including 9.0

After:

This means that publishers may install Google SDK 8.3.1 and the versions up to, but not including 8.4

Reasoning:

This change is a compromise between locking the dependency version to ensure every installation has the same dependencies (which is great for stability and finding bugs) and ability for publishers to get bugfixes from Google and other 3rd party SDK dependencies without waiting for new SDK release.

v5.1.0 (7.7.2021)

Added contextual targeting, Contextual Targeting

v5.0.1 (30.4.2021)

Various bugfixes and stability improvements

v5.0.0 (20.4.2021)

Support for Google Mobile Ads SDK 8.3.0

API breaking changes:

• Protocol YLInterstitialDelegate is removed

• Interstitials now use interstitialAd(:String, :InterstitialCompletion, :GAMRequest?) method signature instead of interstitialAd(:String, :UIViewController, :YLInterstitialDelegate)

• App developers need to implement GADFullScreenContentDelegate and set the delegate in the interstitial completion handler.

Changes to YLBannerViewDelegate protocol:

• adViewDidReceiveAd: becomes bannerViewDidReceiveAd:

• adView:didFailToReceiveAdWithError: becomes bannerView:didFailToReceiveAdWithError:

• adViewWillPresentScreen: becomes bannerViewWillPresentScreen:

• adViewWillDismissScreen: becomes bannerViewWillDismissScreen:

• adViewDidDismissScreen: becomes bannerViewDidDismissScreen:

• getDfpRequest() -> DFPRequest becomes getGAMRequest() -> GAMRequest

• adViewWillLeaveApplication is removed

Other:

• Minimum iOS version when using CocoaPods is raised to iOS 10

• Xcode 12.0 or higher is required to build

• Prebid no longer prints its’ version to the console with every ad request