Cxense Display iOS SDK

Quick Start

This quick start shows you how to get started using the Cxense Display SDK. You will create a new iOS project, include the Cxense Display SDK and do your first ad request.

Prerequisites

  • Xcode 8.0 or higher
  • Deployment target of iOS 8.0 or higher

Installation Guide

Cocoapods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate Cxense Display SDK into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'CxenseDisplaySDK', '~> 3.1'

Then, run the following command:

$ pod install

Manual

A simple app with ads

Creating a new project

  1. Open up Xcode and navigate to File > New > Project. Select Single View Application and press Next.
  2. Choose a name for your project (in this case CxenseDisplayExample) and make sure Objective-C is selected as the language.
  3. Choose a location for your project and click Create. Your project should look something like this:

Adding the SDK to your project

If you don’t already have the Cxense Display SDK you can download it from the Cxense Display website.

  1. Add the files to your project by right- clicking on the CxenseDisplayExample project. ChooseAdd files to “CxenseDisplayExample”.
  2. Add the entire Cxense Display SDK folder to your project. Check Copy items if needed.
  3. The SDK Library references the following frameworks which may not already be part of your project.
    • AdSupport.framework
    • CFNetwork.framework
    • CoreGraphics.framework
    • CoreMotion.framework
    • CoreTelephony.framwork
    • EventKit.framework
    • EventKitUI.framework
    • MediaPlayer.framework
    • MessageUI.framework
    • MobileCoreServices.framework
    • SystemConfiguration.framework
    • QuartzCore.framework
    • libsqlite3.0.dylib
    • libz.dylib
      To add these frameworks, double-click the project name in the left navigation. Under the Build Phases tab, open the Link Binary With Libraries dropdown. Add the frameworks using the + button the becomes visible.
  4. Add the -ObjC linker flag to your targets Build Settings

Your first ad request

Now that you have a project with the Cxense Display SDK referenced you are ready to start displaying ads in your application. Ads are displayed using a CxenseDisplayAdView. You can add this view through either storyboards or code. You configure the adview using a CxenseDisplayAdViewConfiguration object.

  1. Add the view in Code Open up ViewController.m and import the CxenseDisplayAdView header. Create the view and at it as a subview to the controller’s view.
    #import "ViewController.h"
    #import "CxenseDisplayAdView.h"
     
    @interface ViewController ()
    @end
     
    @implementation ViewController
     
    - (void)viewDidLoad {
        [super viewDidLoad];
        CGRect adViewFrame = CGRectMake(0, 0, CGRectGetWidth(self.view.frame), 100.0);
        CxenseDisplayAdView *adView = [[CxenseDisplayAdView alloc] initWithFrame:adViewFrame];
        [self.view addSubview:adView];
    }
     
    @end
  2. Conform to the CxenseAdViewDelegate protocol to respond to events in the ad view. View the CxenseDisplayAdViewDelegate reference for a complete list of available delegate methods.
    @interface ViewController () <CxenseDisplayAdViewDelegate>
    ..
    @end
     
    - (void)viewDidLoad {
        ..
        CxenseDisplayAdView *adView = [[CxenseDisplayAdView alloc] initWithFrame:adViewFrame];
        adView.delegate = self;
        ..
    }
     
    - (void)cxenseDisplayAdView:(CxenseDisplayAdView *)adView
    -           didResizeToSize:(CGSize)size {
        NSLog(@"CxenseDisplayAdView:%@ didResizeToSize:%@", adView, NSStringFromCGSize(size));
    }
     
    @end
  3. Configure the ad view using a CxenseDisplayAdViewConfiguration object.
    CxenseDisplayAdView *adView = ..;
    CxenseDisplayAdViewConfiguration *config = [[CxenseDisplayAdViewConfiguration alloc] init];
    config.baseURL = @"http://stage.emediate.eu/eas";
    config.campaignId = @"12345678987654321";
    config.refreshRate = 30;
    config.preloadCount = 0;
    [adView loadAdsWithConfiguration:config
                               error:nil];


    In this example the view is configured with a baseURL, campaignId, refreshRate and preloadCount. You can verify that there was no errors in your configuration by catching any errors returned.

To make possible to use audience targeted ad campaigns in mobile applications, Display SDK provides user tracking feature. Tracked user identifier is calculated by following algorithm:

If CxenseDisplayAdViewConfiguration#userId is set, then this value will be used as user identifier in any ad calls If CxenseDisplayAdViewConfiguration#userId is not set, then the SDK uses following identifiers: a) If advertising tracking enabled on device, then use IDFA (Identifier for Advertising) b) If advertising tracking disabled on device, then use device's identifier for vendor (UUID) c) If CxenseDisplayAdViewConfiguration#userId has an empty string as a value (””) then user tracking will be disabled for Display SDK

Run the app

Run the app and you should see the ad view with an ad at the top of your view (if you have provided valid baseURL and campaignId/contentUnitId).

What’s next?

Have a look at the code examples below or download the demo app to see more examples of how to implement the Cxense Display SDK in your app.

Code examples

This section provide simple code examples, for a full implementation example download the example app.

Creating a configuration

CxenseDisplayAdViewConfiguration *configuration =[[CxenseDisplayAdViewConfiguration alloc] init];
configuration.baseURL = @"http://url.to.your.admatcher";
configuration.campaignId = @"123456789";
configuration.refreshRate = 20;
configuration.preloadCount = 0;

This sets up a configuration that configures an CxenseDisplayAdView to perform requests to the admatcher at http://url.to.your.admatcher with a campaignId of 123456789 and a refreshrate of 20 seconds. The ad view wont fetch any ads in advance.

Using configuration

CxenseDisplayAdView *adView = [[CxenseDisplayAdView alloc]initWithFrame:CGRectMake(0,0,300,200)];
adView.delegate = self;
[adView loadAdsWithConfiguration:configuration
                           error:nil];

MRAID Support

Cxense Display SDK for iOS has partial MRAID 2.0 support. We currently do not support mraid.resize().

When referring to the MRAID Specification this is the document that apply: IAB MRAID v2.0

Controlling MRAID behavior

If you wish to override the MRAID behavior in the SDK you can implement the MRAID-related delegate methods defined in the CxenseMRAIDDelegate protocol (see CxenseMRAIDDelegate.h). There are a number of features in MRAID that are more intrusive to the app-behavior than others. To support these methods we require you to opt-in by implementing the delegate method cxenseMRAIDAdView:shouldSupportFeature:

# this example opts in to support Calendar and Video
- (BOOL)cxenseMRAIDAdView:(CxenseDisplayAdView *)adView
            shouldSupportFeature:(CxenseMRAIDFeature)feature {
    if (feature == CxenseMRAIDFeatureCreateCalendarEvent ||
        feature == CxenseMRAIDFeaturePlayVideo) {
        return YES;
    }
 
    return NO;
}

You also have the option to override the opt-in by cxenseMRAIDAdView:shouldSupportFeature: method by implementing the specific per-feature delegate method. An example of this is the cxenseDisplayMRAIDAdViewShouldExpand: method.

# support all features that require opt-in (createCalendarEvent, playVideo, expand and storePicture)
- (BOOL)cxenseDisplayMRAIDAdView:(CxenseDisplayAdView *)adView
            shouldSupportFeature:(CxenseMRAIDFeature)feature {
    return YES;
}
 
# prevent an expand command dynamically when it is received by the adview.
- (BOOL)cxenseMRAIDAdViewShouldExpand:(CxenseDisplayAdView *)adView {
 
    // custom logic to decide if expand should be allowed
    BOOL shouldExpand = ..;
 
    if (shouldExpand) {
        return NO;
    }
    return YES;
}

Calendar

It is possible to create calendar events by using the createCalendarEvent function described in the MRAID 2.0 specification. The createCalendarEvent takes one parameter, an event object. The details of this object can be found in the specification, but you can see an example below.


// create a recurring event
// it occur every 2 weeks on wednesdays and fridays
// the recurring event stops recurring after the 1th of April 2016
mraid.createCalendarEvent({
    description: "Status meeting",
    location: "Conference room #14.",
    summary: "Agenda: Discuss mobile ads.",
    start: "2015-05-20T14:00+01:00",
    end: "2015-05-20T16:00+01:00",
    status: "pending",
    recurrence: {
        interval: 2,
        daysInWeek: [3,5],
        expires: "2016-04-01T10:00+01:00"
    }
});

This example will display a EKEventEditViewController which contains this information, and lets the user add the event to the default calender for new events (or choose another one). If you want to override this behavior you can implement the method:

- (BOOL)cxenseMRAIDAdView:(CxenseDisplayAdView *)adView
   shouldAddCalendarEvent:(NSDictionary *)eventDictionary {
 
}

If you’re doing a custom implementations for handling Calendar events you can use the eventDictionary to create a new EKEvent in a EKEventStore by leveraging the CxenseMRAIDCalendarEvent class.

- (BOOL)cxenseDisplayMRAIDAdView:(CxenseDisplayAdView *)adView
          shouldAddCalendarEvent:(NSDictionary *)eventDictionary {
    CxenseMRAIDCalendarEvent *mraidEvent = [CxenseMRAIDCalendarEvent eventWithEventDictionary:eventDictionary];
 
    // the event store for the new event
    EKEventStore *store = [EKEventStore new];
 
    // the new event
    EKEvent *newEvent = [mraidEvent eventInEventStore:store];
 
    // do something with the event
 
    return NO;
}

Resizing of Ads

We differentiate between two kinds of ads in Cxense Display; Responsive Ads and Non-responsive Ads. Depending on the type of ad we scale the content to fit within the CxenseDisplayAdView container. We also support two different modes of the CxenseDisplayAdView; CxenseDisplayAdViewModeDefault and CxenseDisplayAdViewModeDynamicHeight. The mode decide if the view should change its height to fit the ad (while maintaining its aspect ratio) or not.

Responsive Ads

Creatives that are flagged as responsive in the booking interface will not be scaled in the CxenseDisplayAdView container. It is up to responsive creatives to automatically adjust to the container’s size.

Booking a responsive ad

By default all booked ads are flagged as non-responsive. Too book a responsive ad you need to check the 'Mobile SDK Responsive' checkbox which is available under “More options” when editing a creative. Below are two screenshots displaying where the checkbox can be found.

Adding a Html Creative

Checking the Mobile SDK Responsive checkbox

Non-responsive Ads

Any creatives where the Mobile SDK Responsive checkbox is deselected (default) will be treated as creatives that might need to scale to fit within the container. The Cxense Display SDK will use the Campaign Size to determine how large a creative should be. This means that it is important to respect the size and aspect ratio of a campaign when booking creatives.

Ad View Modes

The two different modes:

CxenseDisplayAdViewModeDefault

The default behavior of the CxenseDisplayAdView is to change the size of the internal webview to fit within the container, while keeping the container at its original size. If the ad is responsive the webview will always be sized to the full width and height of the container.

CxenseDisplayAdViewModeDynamicHeight

If you want the CxenseDisplayAdView container to automatically change its height depending on the ad it is displaying, you can set the mode to DynamicHeight.

Resize examples

Here are some brief examples of how the resizing works with different sizes of ads and with different types of ad content.

Non-responsive ad, default mode

  1. A campaign is booked with the size 600×400.
  2. An Image creative is added to the campaign, the Mobile SDK Responsive checkbox is not selected.

When this ad is displayed in a CxenseDisplayAdView it will be scaled based on the size 600×400. If the container has the size 300×200 the creative will be scaled to 50% width and height to fit within the container.

Non-responsive ad, default mode, different aspect ratio container

  1. A campaign is booked with the size 600×400.
  2. An HTML creative is added to the campaign, the Mobile SDK responsive checkbox is not selected.
  3. The ad is displayed in a CxenseDisplayAdView with the size 300×300 and default mode.

This ad will be displayed in a webview with the size 300×200 that is aligned within the container view. The container view does not change size.

Non-responsive ad, dynamic height mode, different aspect ratio container

  1. A campaign is booked with the size 600×400.
  2. An HTML creative is added to the campaign, the Mobile SDK responsive checkbox is not selected.
  3. The ad is displayed in a CxenseDisplayAdView with the size 300×300 and dynamic height mode.

This ad will be displayed in a webview with the size 300×200 that is aligned within the container view. The container view changes its size to 300×200.

Responsive ad, default mode, different aspect ratio container

  1. A campaign is booked with the size 600×400.
  2. A HTML creative is added to the campaign, the Mobile SDK responsive checkbox is selected.
  3. The ad is displayed in a CxenseDisplayAdView with the size 300×300.

This ad will be displayed, without any form of scaling, in a webview with the same size as the container view (300×300).

Required Libraries

Name Description
AdSupport.framework
Foundation.framework
CoreGraphics.framework
CoreMotion.framework
CoreTelephony.framework CoreTelephony.framework is used to get more information about the users connection.
Currently it is only used for checking if the current WWAN- connection is GPRS or Edge.
EventKit.framework
EventKitUI.framework
MediaPlayer.framework
MessageUI.framework
MobileCoreServices.framework
SystemConfiguration.framework SystemConfiguration.framework is needed to get information about the network connection available on the device.
QuartzCore.framework
libsqlite3.dylib
libz.dylib

App Transport Security

Somewhere in 2017 Apple will require all applications submitted to App Review to have ATS enabled OR to have justification for applications with partially / fully disabled ATS. Cxense Display SDK supports work in applications with ATS (App Transport Support) enabled, but please pay attention that it can use 3rd party tags (creatives configured on ad server) that use insecure connections. For such cases you will need to disable ATS in your application. Here how you can do this:

  1. For applications targeted to iOS 10, add following configuration to application’s Info.plist file:
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoadsInWebContent</key>
        <true/>
    </dict>
  2. For applications targeted to previous versions of iOS, add following configuration to application’s Info.plist file:
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>

Release notes

Version Release Date Notes
3.1.6 2018-04-06 Support of opting-out from user tracking was added as a small addition current user tracking functionality.
3.1.5 2018-02-27 Parameters values limit was added. Parameters longer than 42 symbols are no longer allowed.
3.1.4 2017-06-21 Support of IDFA in ad requests was added.
3.1.0 2017-05-19 Multiple internal optimizations (networking engine was reimplemented, obsolete 3rd party libraries were removed).
3.0.15 2017-04-22 Minimal deployment target was updated to 8.0.
3.0.11 2016-12-28 Support of rendering third party creative tags was added.
3.0.10 2016-11-03 Cocoapods support was added. It is now possible to resolve new versions of the SDK automatically through Cocoapods configuration.
3.0.9 2016-10-20 Public documentation update (information about ATS (App Transport Security) was added).
3.0.6 2016-06-25 Bugfixes and public documentation update.
3.0.4 2016-02-03 * Fixed bug with User-Agents.
* Added better support for utf-8 encoded parameters.
3.0.1 2016-01-04 Added missing bitcode support
3.0.0 2015-11-20 * Added partial MRAID 2.0 Support.
* Changed how ads are scaled/resized in the adview container.
2.1.2 2015-04-24 * Fixed a bug which prevented device targeting from working properly.
* Fixed a bug which caused the adview to layout its webview incorrectly.
2.1 2015-04-14 * Now supports parsing of HTML Comments to specify resizing behavior on a creative-level (from the booking system).
* Bugfixes.
2.0 2015-02-04 * SDK now requires iOS 6.0+
* Ads that are larger than the size of the CxenseDisplayAdView will now be resized (scaled) to fit inside the view.
* Ads that are larger than the maxsize of the CxenseDisplayAdView can be aligned within the view (left, right, center).
* There is now only one AdView class.
* Separated the delegate protocols to own headerfiles (see CxenseDisplayAdViewDelegate.h and CxenseMRAIDDelegate.h).
* Now support MRAID command for adding Calendar events.
* Bugfixes.
Cxense © 2012 | Support