iOS SDK
|
|
Version #: 3.1.0 |
Updated: 03-30-18 |
Quick download:
|
|
|
|
Step 1: Integrating the SDK
AerServ offers 3 options for integration:
1-1. CocoaPods
In the same directory as your YOUR_PROJECT.xcodeproj, create an empty file named Podfile and copy and paste the following:
source 'https://bitbucket.org/aerservllc/ios-sdk-pod.git'
platform :ios, '8.0'
pod 'ios-sdk-pod'
Ensure your project has been closed. Using the terminal, navigate to the directory containing the Podfile and run the command: pod install. Once the installation finishes, use YOUR_PROJECT.xcworkspace to access your project moving forward.
Inside the xcworkspace there should be a Pods directory included with a ios-sdk-pod sub-directory.
Select all Device Orientation inside "Deployment Info" field under the General tab.
Inside your application's Info.plist, add the following keys with short descriptions of usage.
- NSLocationWhenInUseUsageDescription: Location is used to help target content to your general area
The following keys and permissions are made available for MRAID ad functionality:
- NSCameraUsageDescription: Camera access required to take photos
- NSPhotoLibraryUsageDescription: Photo Library access required to store pictures
1-2. Static Integration
Download the latest iOS SDK here.
Unzip the downloaded SDK package file and copy the AerServSDK.framework found at the path target/aerserv-ios-sdk/lib/ into your Xcode project.
For your target's Linked Frameworks and Libraries, link the following:
- AerServSDK.framework
- WebKit.framework
- libxml2.2.tbd
Select all Device Orientation inside "Deployment Info" field under the General tab.
Additional Build Settings that need to be configured are as follows:
- Add the linker flag -ObjC to the "Other Linker Flags" field inside the Linking section.
- Add the directory path to the AerServSDK.framework to “Framework Search Paths" inside the Search Paths section; select it as recursive.
Inside your application's Info.plist, add the following keys with short descriptions of usage.
- NSLocationWhenInUseUsageDescription: Location is used to help target content to your general area
The following keys and permissions are made available for MRAID ad functionality
- NSCameraUsageDescription: Camera access required to take photos
- NSPhotoLibraryUsageDescription: Photo Library access required to store pictures
1-3. Swift Integration
When you’re using Swift, you will need to create a Objective-C bridging header after completing Step 1-1. CocoaPods or Step 1-2. Static Integration.
- Create AerServSDK-Bridging-Header.h inside your project.
- Inside the header file, add the following line:
#import <AerServSDK/AerServSDK.h>
- Add the bridging header that was just created inside Build Setting → Swift Compiler - General → Objective-C Bridging Header.
Step 2: Initializing AerServSDK
You must initialize our SDK before loading any ads. Initializing AerServSDK will update server-side configurations and additionally initialize any mediated ad sources.
Within the AerServ dashboard, click on the inventory tab and edit the specific application that is being integrated. There will be an App ID associated to that application. Use that App ID to call AerServSDK's initializeWithAppID: in the early phases of the application. Suggested place to kick off the initialization process is in the application's AppDelegate inside the application:didFinishLaunchingWithOptions: method.
#import <AerServSDK/AerServSDK.h>
...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
// initialize AerServSDK with an App ID
[AerServSDK initializeWithAppID:@"1000473"]; // replace 1000473 with your appliciation's App ID
...
return YES;
}
import AerServSDK
...
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
...
// initialize AerServSDK with an App ID
AerServSDK.initialize(withAppID: "100473")
...
return true
}
Step 3: Display Banner Ads
Create an ASAdView object by passing in a placement setup on the AerServ dashboard as well as the banner's size. Refer to ASAdView.h for AerServSDK's predefined sizes.
#import <AerServSDK/AerServSDK.h>
...
ASAdView *asAdView = [ASAdView viewWithPlacementID:@"1024876" andAdSize:ASBannerSize];
import AerServSDK
...
var asAdView = ASAdView(placementID: “1024876”, andAdSize: ASBannerSize)
Add the ASAdView object to your application's view.
[self.view addSubview:asAdView];
view.addSubview(asAdView!)
In the view controller that the ASAdView object is added to, make sure that the view controller adheres to the ASAdViewDelegate protocol. Additionally, add the callback viewControllerForPresentingModalView that will return itself.
@interface ViewController() <ASAdViewDelegate>
...
- (UIViewController*)viewControllerForPresentingModalView {
return self;
}
class ViewController: UIViewController, ASAdViewDelegate {
...
func viewControllerForPresentingModalView() -> UIViewController! {
return self
}
}
Lastly, kick off the ad request by loading the ad.
Additional Banner Callbacks
You can additionally assign a delegate to listen for the banner's callback events. A few of the callbacks that can be listened to are:
Objective-C
- (void)adViewDidLoadAd:(ASAdView *)adView;
- (void)adViewDidPreloadAd:(ASAdView *)adView;
- (void)adViewDidFailToLoadAd:(ASAdView *)adView withError:(NSError *)error;
- (void)adWasClicked:(ASAdView *)adView;
Swift
func adViewDidLoadAd(_ adView: ASAdView!)
func adViewDidPreloadAd(_ adView: ASAdView!)
func adViewDidFail(toLoadAd adView: ASAdView!, withError error: Error!)
func adWasClicked(_ adView: ASAdView!)
Please refer to ASAdView.h for all available callbacks and descriptions of each. Settings for supplying ad targeting key words, specifying the banner refresh time interval, preloading, and more can be found in the ASAdView header as well.
Step 4: Displaying Interstitial Ads
Create an ASInterstitialViewController object with a placement setup on the AerServ dashboard and a delegate that conforms to ASInterstitialViewControllerDelegate.
#import <AerServSDK/AerServSDK.h>
...
@interface ViewController() <ASInterstitialViewControllerDelegate>
@property (nonatomic, strong) ASInterstitialViewController *asInterstitialVC;
...
self.asInterstitialVC = [ASInterstitialViewController viewControllerForPlacementID:@"1000741" withDelegate:self];
import AerServSDK
…
class ViewController: UIViewController, ASInterstitialViewControllerDelegate {
var asInterstitialVC: ASInterstitialViewController?
...
asInterstitialVC = ASInterstitialViewController(forPlacementID: “1000741”, with:self)
}
Start the ad request by loading an ad with your specified settings.
[self.asInterstitialVC loadAd];
asInterstitialVC?.loadAd()
When the ad is ready, a callback event will be triggered. From the callback, the interstitial ad can be shown from a parent view controller.
- (void)interstitialViewControllerAdLoadedSuccessfully:(ASInterstitialViewController *)viewController {
[viewController showFromViewController:aViewController];
}
func interstitialViewControllerAdLoadedSuccessfully(_ viewController: ASInterstitialViewController!) {
asInterstitialVC?.show(from: self)
}
Optional Interstitial Steps
Preloading Interstitial Ads
Preloading an ad works in a similar fashion. Before loading the ad, the isPreload flag should be set to YES. Another callback event can be listened to for notification that a preloaded ad is ready to be shown.
Objective-C
@property (nonatomic, assign) BOOL didPreload;
...
self.didPreload = NO;
self.asInterstitialVC.isPreload = YES;
[self.asInterstitialVC loadAd];
...
- (void)interstitialViewControllerDidPreloadAd:(ASInterstitialViewController *)viewController {
NSLog(@"---- Interstitial View Controller Did Preload Ad");
self.didPreload = YES;
}
...
if(self.didPreload)
[self.asInterstitialVC showFromViewController:aViewController];
Swift
var didPreload = false
asInterstitialVC?.loadAd()
...
func interstitialViewControllerDidPreloadAd(_ viewController: ASInterstitialViewController!) {
print(“---- Interstitial View Controller Did Preload Ad”)
didPreload = true
}
…
if(didPreload) {
asInterstitialVC?.show(from: aViewController)
}
NOTE:
If placements that share the same ad source and credentials are preloaded many times, only one of the view controllers can have a PRELOAD_READY event for a specific mediated SDK credential. All subsequent requests will failover. This is because once a view controller has PRELOAD_READY, no other view controllers can use that ad object. If a preloaded ad will not be used, you need to deallocate the view controller by setting it to nil.
Additional Interstitial Callbacks
Other callback events that can be listened to are:
Objective-C
- (void)interstitialViewControllerWillAppear:(ASInterstitialViewController *)viewController;
- (void)interstitialViewControllerDidAppear:(ASInterstitialViewController *)viewController;
- (void)interstitialViewControllerWillDisappear:(ASInterstitialViewController *)viewController;
- (void)interstitialViewControllerDidDisappear:(ASInterstitialViewController *)viewController;
- (void)interstitialViewControllerAdWasTouched:(ASInterstitialViewController *)viewController;
- (void)interstitialViewControllerAdFailedToLoad:(ASInterstitialViewController *)viewController withError:(NSError *)error;
Swift
func interstitialViewControllerWillAppear(_ viewController: ASInterstitialViewController!)
func interstitialViewControllerDidAppear(_ viewController: ASInterstitialViewController!)
func interstitialViewControllerWillDisappear(_ viewController: ASInterstitialViewController!)
func interstitialViewControllerDidDisappear(_ viewController: ASInterstitialViewController!)
func interstitialViewControllerAdWasTouched(_ viewController: ASInterstitialViewController!)
func interstitialViewControllerAdFailed(toLoad viewController: ASInterstitialViewController!, withError error: Error!)
Please refer to ASInterstitialViewController.h for all available callbacks and descriptions for each. Settings for supplying ad targeting key words, video player controls, and more can be found in the ASInterstitialViewController header as well.
Additional Settings
Header Bidding Requests
Both banners and interstitials have the ability to initiate header bidding requests.
asAdView.useHeaderBidding = YES;
...
[asAdView loadAd];
asInterstitialVC.useHeaderBidding = YES;
...
[asInterstitialVC loadAd];
Pausing & Resuming Video Ads
Both banners and interstitials have the ability to pause and resume play of VAST video ads.
[asAdView pause];
...
[asAdView play];
[asInterstitialVC pause];
...
[asInterstitialVC play];
Virtual Currency
Once you have setup your placement with virtual currency, there are two additional callbacks that conform to the protocol ASInterstitialViewControllerDelegate. The first callback will notify that the virtual currency data has loaded.
- (void)interstitialViewControllerDidVirtualCurrencyLoad:(ASInterstitialViewController *)viewController vcData:(NSDictionary *)vcData;
The second callback will notify when the virtual currency has been rewarded.
- (void)interstitialViewControllerDidVirtualCurrencyReward:(ASInterstitialViewController *)viewController vcData:(NSDictionary *)vcData;
For both of these callbacks, there is a vcData dictionary object attached that will contain the keys 'name' and 'rewardAmount'. In lieu of 5-2, the dictionary object returned during the virtual currency load also contains the keys 'buyerName' and 'buyerPrice' in regards to the ad's transaction information.
Ad Transaction Information
During the process of showing an ad, the AerServSDK will additionally return information pertaining to the buyer for your ad space and the price that the ad space was bought for. This detailed information can be found from these callbacks:
For banners:
- (void)adView:(ASAdView *)adVidew didShowAdWithTransactionInfo:(NSDictionary *)transcationData;
For interstitials:
- (void)interstitialViewController:(ASInterstitialViewController *)viewController didShowAdWithTransactionInfo:(NSDictionary *)transcationData;
The transactionData dictionary object contains keys for 'buyerName' and 'buyerPrice' that can be accessed for the transaction information values.
As mentioned in 5-1, the transaction information is available for interstitial ads at load if virtual currency is enabled through the virtual currency load callback.
Adding Keyword Tagging
For details about keyword tagging, click here.
Additional keyword tagging to your ad request can be done by assigning an array of strings to the keyWords property. This can be done for both interstitials and banners.
asAdView.keyWords = @[@"banner", @"key", @"word", @"tagging"];
...
asInterstitialVC.keyWords = @[@"interstitial", @"key", @"word", @"tagging"];
Adding Publisher Keys
For details about publisher keys, click here.
Custom revenue reports can be generated via the SDK by assigning a dictionary object with publisher key value pairs to the pubKeys property. This is available for both interstitials and banners.
asInterstitialVC.pubKeys = @{@"channel_category" : @"music", @"content_rating" : @"4 stars"};
...
asAdView.pubKeys = @{@"partner_name" : @"bloomberg", @"episode_id" : @"77889"}
Enabling Geolocation Targeting
If your application already requests permission for geolocation, skip this step.
Enabling geolocation will help target ads relevant to your user's physical location. This can be done by adding key-value pairs to your application's Info.plist. The keys will be NSLocationAlwaysUsageDescription & NSLocationWhenInUseUsageDescription. The value for both will be a string that will be displayed when your application is requesting for geolocation permission.
<key> NSLocationAlwaysUsageDescription </key>
<string> Location is used to help target content to your general area </string>
<key> NSLocationWhenInUseUsageDescription </key>
<string> Location is used to help target content to your general area </string>
Disabling App Transport Security for iOS 9+
Select your application's Info.plist, right-click on it and open as source code. Copy the following code into your Info.plist's xml.
<key> NSAppTransportSecurity </key>
<dict>
<key> NSAllowsArbitraryLoads </key>
<true/>
</dict>
Muting Interstitial Ads
Video ads can be muted programmatically. This setting will not affect SDK mediation.
For Interstitials
asInterstitialVC.isMuted = YES;
For Banners
asAdView.isMuted = YES;
Muting is turned off by default. If isMuted is set to NO, the control for mutability falls back to the setting on the AerServ dashboard.
Disabling Interstitial Animation
To disable the animation for when the interstitial view controller is presented,
asInterstitialVC.hasAnimation = NO;
This setting will not affect SDK mediation.
Version History
View iOS Version History
Comments