Versions Compared

Old Version 4

changes.mady.by.user Phunware Inc.

Saved on

compared with

New Version Current

changes.mady.by.user Phunware Inc.

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Advertising SDK Integration Guide (iOS)

Version 3.1.3

This is Phunware's iOS SDK for the MaaS Advertising module. http://ads.tapit.com/ for more details and to sign up.

 

Getting Started

  • Download MaaS Advertising and run the included sample app.
  • Continue reading below for installation and integration instructions.
  • Be sure to read the documentation for additional details.

 

Installation

Required Frameworks

These frameworks are required.

MaaS Advertising has a dependency on MaaSCore.framework, which is available here: https://github.com/phunware/maas-core-ios-sdk

It's recommended that you add the MaaS frameworks to the 'Vendor/Phunware' directory. This directory should contain MaaSCore.framework and MaaSAdvertising.framework, as well as any other MaaS frameworks that you are using.

In the build settings for your target, you must include the following "Other Linker Flags:" -ObjC

No Format
MaaSCore.framework
SystemConfiguration.framework
QuartsCore.framework
CoreTelephony.framework
MessageUI.framework
EventKit.framework
EventKitUI.framework
CoreMedia.framework
AVFoundation.framework
MediaPlayer.framework
AudioToolbox.framework
AdSupport.framework - enables support for IDFA
StoreKit.framework - enables use of SKStoreProductViewController and displays app store ads without leaving your app

 

Optional Frameworks

CoreLocation is used for geo-targeting ads. Apple mandates that your app have a good reason for enabling location services and will deny your app if location is not a core feature for your app.

No Format
CoreLocation.framework

 

Required Bundles

PWAds.bundle includes files needed for media-rich advertisements that make use of device-specific features. It is included with this sample app.

No Format
PWAds.bundle

 

Integration

The MaaS Advertising SDK allows developers to serve many types of ads, including banner, interstitial and video ads.

 

Initialization

 

Code Block
themeMidnight
// In your AppDelegate.m file:
#import <MaaSAdvertising/PWAdsAppTracker.h>

...

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    PWAdsAppTracker *appTracker = [PWAdsAppTracker sharedAppTracker];
    [appTracker reportApplicationOpen];
    return YES;
}

 

Banner Usage

 

Code Block
themeMidnight
// In your .h file:
#import <MaaSAdvertising/PWAdsBannerAdView.h>
@property (retain, nonatomic) PWAdsBannerAdView *pwAd;

...

// In your .m file:
#import <MaaSAdvertising/PWAds.h>
...
// Init banner and add to your view:
pwAd = [[PWAdsBannerAdView alloc] initWithFrame:CGRectMake(0, 0, 320, 50)];
[self.view addSubview:self.pwAd];

// To kick off banner rotation:
[self.pwAd startServingAdsForRequest:[PWAdsRequest requestWithAdZone:@"**YOUR ZONE ID**"]];

...

// To hide and cancel ads: 
[self.pwAd hide];
[self.pwAd cancelAds];

 

Interstitial Usage

Show Modally

Code Block
themeMidnight
// In your .h file:
#import <MaaSAdvertising/PWAdsInterstitialAd.h>
...
@property (retain, nonatomic) PWAdsInterstitialAd *interstitialAd;

...

// In your .m file: 
#import <MaaSAdvertising/PWAds.h>
...
// Init and load interstitial:
self.interstitialAd = [[PWAdsInterstitialAd alloc] init];
self.interstitialAd.delegate = self; // notify me of the interstitial's state changes
PWAdsRequest *request = [PWAdsRequest requestWithAdZone:@"**YOUR ZONE ID**"];
[self.interstitialAd loadInterstitialForRequest:request];

...

- (void)pwInterstitialAdDidLoad:(PWAdsInterstitialAd *)interstitialAd {
    // The ad is ready for display. Show it!
    [self.interstitialAd presentFromViewController:self];
}

 

Include in Paged Navigation

Code Block
themeMidnight
@property (retain, nonatomic) PWAdsInterstitialAd *interstitialAd;

...

// Init and load interstitial:
self.interstitialAd = [[PWAdsInterstitialAd alloc] init];
PWAdsRequest *request = [PWAdsRequest requestWithAdZone:@"**YOUR ZONE ID**"];
[self.interstitialAd loadInterstitialForRequest:request];

...

// If the interstitial ad is ready, show it using:
if( self.interstitialAd.isLoaded ) {
    [self.interstitialAd presentInView:self.view];
}

 

Video Ads Usage

When requesting a video ad from the server, a TVASTAdsRequest object must be instantiated and its zoneId parameter specified. This parameter is required for a successful retrieval of the ad.

Code Block
themeMidnight
	// Create an adsRequest object and request ads from the ad server with your own ZONE_ID.
    TVASTAdsRequest *request = [TVASTAdsRequest requestWithAdZone:**YOUR ZONE ID**;
    [_videoAd requestAdsWithRequestObject:request];

 

If you want to specify the type of video ad you are requesting, use the call below.

Code Block
themeMidnight
	TVASTAdsRequest *request = [TVASTAdsRequest requestWithAdZone:**YOUR ZONE ID**];
    [_videoAd requestAdsWithRequestObject:request andVideoType:PWAdsVideoTypeMidroll];

 

Essentially, what needs to be included in the code is as follows:

Code Block
themeMidnight
- (void)viewDidLoad
{
    [super viewDidLoad];
	// Do any additional setup after loading the view.
    _videoAd = [[PWAdsVideoInterstitialAd alloc] init];
    _videoAd.delegate = self;
    
    // OPTIONAL: Override the presentingViewController (defaults to the delegate).
    // _videoAd.presentingViewController = self;
}

- (void)requestAds {    
    // Create an adsRequest object and request ads from the ad server with your own ZONE_ID.
    TVASTAdsRequest *request = [TVASTAdsRequest requestWithAdZone:**YOUR ZONE ID**];
    [_videoAd requestAdsWithRequestObject:request];
    
    // If you want to specify the type of video ad you are requesting, use the call below.
    // [_videoAd requestAdsWithRequestObject:request andVideoType:PWAdsVideoTypeMidroll];
}

- (IBAction)onRequestAds {
    [self requestAds];
}

- (void)pwVideoInterstitialAdDidFinish:(PWAdsVideoInterstitialAd *)videoAd {
    NSLog(@"Override point for resuming your app's content.");
    [_videoAd unloadAdsManager];
}

- (void)viewDidUnload {
    [_videoAd unloadAdsManager];
    [super viewDidUnload];
}

- (void)pwVideoInterstitialAdDidLoad:(PWAdsVideoInterstitialAd *)videoAd {
    NSLog(@"We received an ad... now show it.");
    [videoAd playVideoFromAdsManager];
}

- (void)pwVideoInterstitialAdDidFail:(PWAdsVideoInterstitialAd *)videoAd withErrorString:(NSString *)error {
    NSLog(@"%@", error);
}

 

Native Ad Usage

 

 

Code Block
themeMidnight
// In your .h file:
#import <MaaSAdvertising/PWAdsNativeAdManager.h>

@interface MyViewController : UIViewController <PWAdsNativeAdDelegate>

@property (nonatomic, retain) PWAdsNativeAdManager *pwNativeManager;
...

// In your .m file:
#import <MaaSAdvertising/PWAds.h>
...
pwNativeManager = [[PWAdsNativeAdManager alloc] init];
pwNativeManager.delegate = self;
PWAdsRequest *request = [PWAdsRequest requestWithAdZone:*YOUR ZONE ID* andCustomParameters:params];
[pwNativeManager getAdsForRequest:request withRequestedNumberOfAds:10];
...

- (void)pwNativeAdManagerDidLoad:(PWAdsNativeAdManager *)nativeAdManager {
    PWAdsNativeAd *newAd = [nativeAdManager.allNativeAds objectAtIndex:0];

    // Get data from `newAd` and add fields to your view:
    ...
    UILabel *titleLabel = [[UILabel alloc] init];
    [titleLabel setFrame:CGRectMake(10,50,300,20)];
    titleLabel.backgroundColor=[UIColor clearColor];
    titleLabel.textColor=[UIColor blackColor];
    titleLabel.userInteractionEnabled=YES;
    titleLabel.text = newAd.adTitle;
    [self.view addSubview:titleLabel];
    [titleLabel release];
    ...

    // Add a touch recognizer to native element(s) to enable landing page access.
    UITapGestureRecognizer *tapGestureRecognizer = [[UITapGestureRecognizer alloc] initWithTarget:self action:@selector(labelTapped)];
    tapGestureRecognizer.numberOfTapsRequired = 1;
    [titleLabel addGestureRecognizer:tapGestureRecognizer];
    // Log the native ad impression.

    [nativeAdManager logNativeAdImpression:newAd];
}

- (void)labelTapped {
    PWAdsNativeAd *newAd = [pwNativeManager.allNativeAds objectAtIndex:0];
    [pwNativeManager nativeAdWasTouched:newAd];
}

- (void)pwNativeAdManager:(PWAdsNativeAdManager *)nativeAdManager didFailToReceiveAdWithError:(NSError *)error {
    NSLog(@"Native Ad Manager failed to load with the following error: %@", error.localizedDescription);
}
...

 

Listen for Location Updates

If you want to allow for geotargeting, listen for location updates:


Code Block
themeMidnight
@property (retain, nonatomic) CLLocationManager *locationManager;

...

// Start listening for location updates:
self.locationManager = [[CLLocationManager alloc] init];
self.locationManager.delegate = self;

// iOS 8 check:
if ([self.locationManager respondsToSelector:@selector(requestWhenInUseAuthorization)]) {
    [self.locationManager requestWhenInUseAuthorization];
}
[self.locationManager startUpdatingLocation];

...

- (void)locationManager:(CLLocationManager *)manager didUpdateToLocation:(CLLocation *)newLocation fromLocation:(CLLocation *)oldLocation {
    // Notify the PW Ads banner when the location changes. New location will be used the next time an ad is requested.
    [self.pwAd updateLocation:newLocation];
}

...

// To stop monitoring the location when complete and conserve battery life:
[self.locationManager stopMonitoringSignificantLocationChanges];

 

Customization Options

If you want to customize the appearance of the in-app browser controller that appears when a user taps on an ad, follow the below instructions.

  1. To customize the background color of the browser controller toolbar, add the key pwAdsToolbarBgColor with a color value represented in RGBA format (ex. orange = 255 149 0 1) to your app's Info.plist file. 
  2. To customize the tint color of the browser controller toolbar items, add the key pwAdsToolbarTintColor with a color value represented in RGBA format (ex. blue = 0 0 255 1) to your app's Info.plist file.

If you want to customize the appearance of the "close" button for interstitial ads, follow the below instructions:

  1. Create "close" button images at 32x32 pixels @1x and 64x64 pixels @2x.

  2. Name the newly created images pwCustomClose.png and pwCustomClose@2x.png.

  3. Add pwCustomClose.png and pwCustomClose@2x.png images to your Xcode project.