Millennial Media (formerly Jumptap) iOS SDK Integration

From Millennial Media
Jump to: navigation, search


Contents

Overview

This wiki page describes the Millennial Media (formerly Jumptap) iOS ad library installation and use for iPhone, iPod Touch & iPad developers. You can also access the FAQ and Sample iPhone/iPad app for troubleshooting.

In November 2013 Millennial Media acquired Jumptap. This wiki page referes to the SDK version build and maintained by Jumptap prior to the acquisition.

Important Note: IDFA

The Identifier for Advertising (IDFA) was introduced in iOS 6. It's used by advertisers for tracking conversions and advanced targeting, among other things. IDFA is intended to replace UDID as the device identifier.

Millennial Media's (formerly Jumptap) SDK (as of version 2.0.16.0) supports the new iOS 6 functionality, including the Identifier for Advertising (IDFA) and advertisingTrackingEnabled features. These allow advertisers to track conversions and perform advanced targeting. Publishers that support these features should, in turn, expect to yield improved advertising revenue on their mobile properties.

Downloading the library


SDK with IDFA

  • This SDK will enable your app to:
    • Be compatible with IDFA for devices using iOS 6 (or higher). Your app will be able to utilize the IDFA to support conversion tracking and advanced targeting on devices using iOS 6 and higher.
  • Download here: SDK with IDFA and without UDID


Note on Location Use

Impact of Apple's policy change regarding the use of CoreLocation:

For apps that are already using CoreLocation, you may continue to pass location data to the Jumptap library via the 'location' callback described in the documentation below.

For apps that are not using CoreLocation within their app, you should be aware of the following:

  1. Even if it won't be used, you must still link against CoreLocation to guarantee runtime stability
  2. This version of the Millennial Media SDK sets allowLocationUse to NO by default.
  3. Apple has informed us that even if your app is not using location for another purpose, it is acceptable to use the user's location if you provide them with notice. This notice should indicate that their location will be used to deliver targeted advertising and give them the option of disallowing this. Once the user has allowed this twice, the notice does not need to be shown again.

Installation

To use the library, add the Millennial Media library code and headers to your project. The directions below reference jtUniversalLib.a. If you are using the no-UDID version of the SDK, the file will be named jtUniversalLibNoUDID.a

Upgrading from a Previous Millennial Media SDK

If you are upgrading from a previous version of the Millennial Media Ad SDK, you'll notice there are substantial differences in Installation instructions.

If this is the case, please do the following:

  • Remove the previous jtUniversalLib.a from your project
  • Check your application and project build settings, removing references to the Millennial Media SDK from the 'Library Search Paths'
  • Follow the instructions below

Adding Frameworks to Your Project

You must add the following frameworks and dynamic libraries to your project:

Frameworks (found in $SDKROOT/System/Library/Frameworks/)

  • AdSupport.framework
  • CoreGraphics.framework
  • CoreLocation.framework
  • MediaPlayer.framework
  • SystemConfiguration.framework
  • AudioToolbox.framework
  • QuartzCore.framework


Dynamic libraries (found in $SDKROOT/usr/lib/)

  • libz.1.2.n.dylib (where n is '5' for the most recent Xcode and '3' for earlier versions)
  • libsqlite3.dylib

These frameworks and dynamic libraries are only used during linking and at run time and will not affect the size of your application.

Frameworks image.png

Configuring Your Project's Build Settings

The following enables you to have the one library listed in your project view but still link against the appropriate library object without getting any errors. This works for switching between the Simulator and Device and from firmware 2.2.1 and up through the latest release.

  1. Unzip the folder to your project directory so that Millennial Media Api is next to Classes
  2. Go into your project
  3. Right Click "Classes" -> Add -> Existing Files : ./JumptapApi/JTAdWidget.h
  4. Right Click "Frameworks" -> Add -> Existing Files : ./JumptapApi/jtUniversalLib.a
  5. Right Click your Project -> Get Info -> Build Tab
    1. Make sure "Configuration" in the top left is set to "All Configurations"
    2. Under the "Architectures" section, set "Base SDK" to "iOS 4.3" (or higher depending on which features you yourself use)
    3. Under the "Deployment" section, set "iPhone OS Deployment Target" to the earliest firmware version you wish to support (FW 3.2 and higher)
    4. Under the "Linking" section, add to "Other Linker Flags" the flag "-ObjC" (without the quotes)

Please also make sure to verify that your "Base SDK" and "iPhone OS Deployment Target" are not overridden in your individual Targets.

When switching from Simulator to Device, make sure that you do not set your "Active SDK" to a version earlier than the "Base SDK" you selected above. Doing so will result in very strange linker errors (or if linking succeeded very strange run time errors).

Newsdkscreen.png

A Note on Building Cross Platform Applications

Configuring your project to build using a 'Base SDK' of 3.0 (or higher) but with a 'Deployment Target' of 2.2.1 or higher is according to Apple's Best Practices.

For more information on this topic, please refer to Apple's documentation (may required developer access):

A Note on Linker Flags

As stated above, you now need to add the "-ObjC" to your "Other Linker Flags". You find this setting by double clicking on your Project (or Application Target), clicking on “Build” and searching for "Other Linker Flags". Make sure this is set for all configurations.

Linkerflag.png

For more information on this topic, please refer to Apple's documentation (may require developer access):

Using the library

Initialization

You must initialize the Millennial Media ad service in order to use it.

+ (void) initializeAdService:(BOOL)allowLocationUse;

Initialization example:

@implementation MyApplicationAppDelegate
+ (void) initialize {
                [super initialize];
                [JTAdWidget initializeAdService:YES];
}
@end

The library's typical use case is as follows.

  • Initialize a the Millennial Media ad service as soon as possible after start up
  • Create a new JTAdWidget specifying its initial CGFrame and which instance of JTAdWidgetDelegate to use
  • Add the widget as a subview of your view

The class you are using as your JTAdWidgetDelegate must support the following callback:

- (NSString *) publisherId: (id) widget;

This is sufficient to get your first ad displayed. Using the ad widget's refreshInterval or by manually invoking refreshAd you can request and show a series of ads.

Basic implementation sample code

// in viewDidLoad:

JTAdWidget *widget = [[JTAdWidget alloc] initWithDelegate:self shouldStartLoading: YES];
widget.frame = CGRectMake(0.0, 410.0, 320.0, 50.0);
widget.refreshInterval = 60;
[self.view addSubview:widget];

// basic delegate methods
- (NSString *) publisherId: (id) theWidget {
  return @"my_publisher_id_supplied_by_jumptap";
}

- (NSString *) adSpot: (id) theWidget {
  // this might vary depending upon what "page" 
  // the user is currently visiting
  return @"my_spot_id_supplied_by_jumptap_which_may_vary_by _page";
}

Initialization Routine

// initializes the JTAdWidget with a delegate which can be invoked for 
// a publisher id, ad spot id, and other questions, and a boolean 
// indicating whether the widget should immediately start displaying ads.
// If the boolean is NO, no ads will be displayed until refreshAd is invoked on the widget.

initWithDelegate: (JTAdWidgetDelegate*) delegate shouldStartLoading: (BOOL) startLoading;

Required methods of the JTAdWidgetDelegate protocol

These all take an argument of the JTAdWidget that is displaying the ads.

// Initializes the jumptap ad service. allowLocationUse should be set to YES to allow
//  the jumptap ad widget to obtain the user's location and to NO to disallow 
+ (void) initializeAdService:(BOOL)allowLocationUse;

// returns a jumptap-assigned publisher id
- (NSString *) publisherId: (id) theWidget;

Optional methods of the JTAdWidgetDelegate protocol

// returns the spot id that should be used for specified widget
- (NSString *) adSpot: (id) theWidget;
// returns the site id that should be used for specified widget
- (NSString *) site: (id) theWidget;

// any general keyword associated with the view the ad is being displayed in.
- (NSString *) query: (id) theWidget;

// The level of adult content allowed to be returned, one of AdultContentAllowed, 
// AdultContentNotAllowed, AdultContentOnly
// Default is AdultContentNotAllowed
- (AdultContent) adultContent: (id) theWidget;	

// Any extra URL parameters (targeting parameters, etc) to be added to the ad request
// These are passed via a NSDictionary and the values should not be URL encoded.
// Supported keys and values are:
// mt-age - user's age in years, integer, 1-199
// mt-gender - user's gender, m or f
// mt-hhi - user's household income range in thousands.
// For example, 030_040 represents an income between 30,000-40,000
// Possible values are:
// 000_015, 015_020, 020_030, 030_040, 040_050, 050_075,
// 075_100, 100_125, 125_150, 150_OVER
// For example, mt-gender=f&mt-age=25&mt-hhi=050_075
// which would be represented in a dictionary as
//
//	return [NSMutableDictionary dictionaryWithObjectsAndKeys: 
//								@"f", @"mt-gender",  
//								@"25", @"mt-age", 
//								@"050_075", @"mt-hhi", 
//								nil, nil];
- (NSDictionary*) extraParameters: (id) theWidget;

// If the ad being requested is an interstitial
// NO - for a standard banner ad
// YES - for an interstitial
// De
- (BOOL) isInterstitial: (id) theWidget;

// These control the presentation of customizable ad units.
// The text color and background color will override the colors
// of the ad units where appropriate.  (The primary use case is text ads.)
- (UIColor *)adBackgroundColor: (id) theWidget;
- (UIColor *)adTextColor: (id) theWidget;

// The following control whether the library will use the Core Location framework to determine the location of 
// the device.  (Alternatively, the application can pass in  a location object.)  If a custom location is
// provided, the widget will not interact with Core Location.  If no custom location is provided, and
// allowLocationUse returns YES, then the widget will attempt to obtain the users location for enhanced 
// targeting.

// Provide the library with access to a CLLocation if already available
- (CLLocation*) location: (id) theWidget;

// indicates that the ad is being interacted with
- (void) beginAdInteraction: (id) theWidget;
- (void) endAdInteraction: (id) theWidget;

// The ad orientation changed
- (void) adWidget: (id) theWidget orientationHasChangedTo: (UIInterfaceOrientation) interfaceOrientation;

// Error when trying to show the ad
- (void) adWidget: (id) theWidget didFailToShowAd: (NSError *) error;

// Error when trying to request the ad
// Note: This error is returned if the ad could not be retrieved for any reason
//       including: no ad is available, network error, incorrect ad spot, etc.
- (void) adWidget: (id) theWidget didFailToRequestAd: (NSError *) error;

// The following provide localization support and allow elements of the
// Millennial Media-supplied ad interaction UI to be overridden with new text.
// You cannot hide these buttons.  If you return nil from your method the default will be used.

// Overrides the default "Click to play video" text.
- (NSString*) getPlayVideoPrompt:(id) theWidget;

// When an ad is clicked on, sometimes an overlay window appears to show the
// contents of the page the advertisement links to.  This overlay window will
// have up to two buttons on it.  One is the "Back" button; the other allows
// the user to open the URL of the page in mobile Safari and has the label "Safari"
// by default.

// Overrides the display of the "Back" button.  The default implementation
// returns "Dismiss" if an interstitial and "Back" otherwise.
- (NSString*) getBackButtonPrompt:(id) theWidget isInterstitial:(BOOL)isInterstitial;

// Overrides the display of the "Safari" button.  The default implementation returns "Safari"
- (NSString*) getSafariButtonPrompt:(id) theWidget;

Properties

Properties that can be set:

Property Notes
refreshInterval Number of seconds for ad auto-refresh. Set to zero to disable auto-refresh. Default is 0. That is, you need to call refreshAd to retrieve an ad by default.
autorotate YES or NO depending upon whether this ad widget should rotate itself to reflect the orientation of the device. Default is NO.
transition Controls the transition to the full ad view, one of TransitionHorizontalSlide, TransitionVerticalSlide, TransitionCurl, TransitionFlip. Default is TransitionHorizontalSlide.

Methods

Methods that can be called:

// triggers an ad refresh
-(void) refreshAd;
Personal tools