Upsight logo Back to top

iOS

Overview


Upsight, formerly PlayHaven, is the most comprehensive analytics and marketing platform for web and mobile apps. We are building a business engine to help our customers better understand user behavior, decide what it means, and act to impact key goals.

If you have any questions, visit the Publish Guide or contact Upsight Support. We also recommend reviewing our Optimization Guides to learn the best practices and get the most out of your Upsight integration.

The Upsight iOS SDK currently supports the following iOS versions:

  • iOS 5.1 - iOS 9.x

Important If you are building for iOS 9 using and old version of the SDK, please disable App Transport Security. You can do this by adding an NSAppTransportSecurity dictionary key in your Info.plist and adding a boolean NSExceptionAllowsInsecureHTTPLoads and setting it to YES. For more information, you can refer to step 7 of our Enterprise Quick Start Guide, but please note that you cannot add arbitrary exemptions like on analytics you must use NSExceptionAllowsInsecureHTTPLoads.

Getting Started

Prerequisites


Token and Secret

Every app on the Upsight Marketing Dashboard has a unique Token and a unique Secret to identify it. These are both alphanumeric strings 32 characters long. The token and secret uniquely identify your application and prevent others from making API requests on your behalf. They are located on the Upsight Dashboard in the App Settings page for your application.

Note Both the Token and the Secret will be required in order to connect your app to the Dashboard.

Placement Tags

Placements are hooks within your app that can trigger Upsight content such as cross-promotions for your other apps or announcements. To create a Placement you will need a Placement Tag to identify the Placement on the Dashboard. To create a Placement Tag, you will need access to the Upsight Dashboard.

It is recommended that you add as many varied placements as possible to give you the most flexibility to experiment and connect with your users throughout the user experience. These placements will remain invisible to your players until content is assigned to them via the Upsight Marketing Dashboard.

In this example, you will create a Placement that can associate with your app launching.

  1. Click on your app on the Upsight Marketing Dashboard homepage.
  2. Click on the App Settings button.
  3. Click on the Placements link.
  4. Click on the Add Placement button.
  5. In the Placement Tag field, enter app_launch.
  6. In the Description field, enter a relevant description.
  7. Click the Save button.

The Add Placement Screen

For more information on Placements, refer to the Placements Guide for best practices and tips.

Content Units

Although your app can be integrated without any Content Units, you can only full experience and test an integration by having a Content Unit that is linked to a Placement on the Upsight Marketing Dashboard. This will allow you to see what your users will see when a Placement is triggered in your app.

In this example, you will create an Internal Cross-Promotion and associate it to your app_launch placement.

  1. Click on your app on the Upsight Marketing Dashboard homepage.
  2. Click on the Add Content button.
  3. Click on on the Add Internal Cross-Promotion button.
  4. Enter Test Ad for the Internal Cross-Promotion name.
  5. Enter name of app(s) for Internal Cross-Promotion.
  6. Upload image(s) associated with Internal Cross-Promotion.
  7. Under Placement(s), check the box for app_launch placement you created.
  8. Click the Publish button.

Add an Internal Cross-Promotion Screen

Getting Started

Step 1 Add Upsight SDK to the Project


Download the SDK

Download the Upsight iOS SDK.

Add the src Directory

From the Upsight iOS SDK archive, add the src directory to your project.

Add JSON Directory

If your project is not already using SBJSON, add the JSON directory to your project.

If your project is already using SBJSON, you may continue to use those classes or exchange them for the classes included in the SDK.

Note Using your own pre-existing SBJSON classes and the Upsight SDK SBJSON classes in the same project is not advised and may cause errors at compilation time.

In the Build Phases > Link Binary with Libraries section, link the binary with the following libraries:

Name Status
AdSupport.framework
Optional
StoreKit.framework
Required
CFNetwork.framework
Required
SystemConfiguration.framework
Required
UIKit.framework
Required
Foundation.framework
Required
CoreGraphics.framework
Required

To configure the Upsight SDK to not use advertising identifier (IDFA), please follow the instructions on the Upsight Help Center.

Disable Automatic Reference Counting

In your project's Build Settings > Apple LLVM 5.1 - Language - Objective C section, set Objective-C Automatic Reference Counting to No. In the Compile Sources section of Build Phases you can add -fno-objc-arc to Compiler Flags for all files within the src and JSON directories.

Disable StoreKit Framework (Optional)

Most applications integrating the Upsight SDK are already linked against StoreKit.framework. If your app does not use the StoreKit.framework and you do not plan to use Virtual Goods Promotions or In-App Purchase Tracking features in your application, it is possible to disable the SDK part supporting those features by setting the preprocessor macro in Build Settings > Apple LLVM 5.0 - Preprocessing > Preprocessor Macros of the project or particular target that is to be linked with the SDK.

Setting Example
Preprocessor Macros
PH_USE_STOREKIT=0

This makes it possible to build the SDK without the StoreKit.framework linked to your project.

Set Ad Support Framework to Optional (iOS 5.1 Only)

If your project needs to support iOS 5.1, make sure to set AdSupport.framework to Optional in the Link Binary With Libraries build phase of your target.

Supporting Xcode Prior to Version 4.5

Versions of Xcode prior to version 4.5 do not include AdSupport.framework. If you are using a version of Xcode prior to 4.5, you will need to disable references to this framework. To do this, set the following preprocessor macro in Build Settings of the project or particular target that is to be linked with the SDK:

Setting Example
Preprocessor Macros
PH_USE_AD_SUPPORT=0
Preprocessor Macros Not Used In Precompiled Headers

SDK Threading Considerations

The Upsight iOS SDK classes should be used from an application's main thread. Doing this is safe as the SDK in itself operates asynchronously and will not block the main thread during its work.

Note Making calls to the SDK from a background thread is not expected and may result in undefined behaviour.

Including Upsight Headers

Make sure you include the Upsight SDK headers in your code wherever you are using Upsight request classes:

#import "PlayHavenSDK.h"

Getting Started

Step 2 Make an Open Call


Making an Open Call is required as it assists in collecting accurate data to measure performance and effectiveness of your implementations.

Note This request is asynchronous and should be performed on the main thread.

You will need to make an open request two application delegate methods. The method that records an app open when the application is first launched:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

And the method that records an app open when the app moves to the foreground after being launched:

- (void)applicationWillEnterForeground:(UIApplication *)application

The app open request is sent using the following code:

[[PHPublisherOpenRequest requestForApp:@"TOKEN" secret:@"SECRET"] send]

The strings TOKEN and SECRET should be replaced with the token and the secret of your application.

Important If you are using the Enterprise and regular SDKs, make sure to call the startSession method before making an PHPublisherOpenRequest Open Call.

Getting Started

Step 3 Requesting Content Units


You will need to incorporate content request calls into your application to display content units that are defined in the Upsight dashboard. Content requests are made using your application token, secret, and a placement tag to identify the placement for which you are requesting content.

The example below demonstrates a content request for the placement app_launch. The showsOverlayImmediately property of the request object is set to YES to show a loading overlay. This is useful if you would like to prevent users from interacting with your UI while the content is loading.

PHPublisherContentRequest *request = [PHPublisherContentRequest
requestForApp:@"Your Token Here"
secret:@"Your Secret Here"
placement:@"app_launch"
delegate:self];
request.showsOverlayImmediately = YES;
[request send];

If you are interested in receiving delegate calls from the request object, you need to implement delegate methods declared in PHPublisherContentRequestDelegate protocol. Refer to the following section as well as the example/PublisherContentViewController.m file for a sample implementation of the request delegate.

Getting Started

Step 4 Test Integration


Build your app and install it onto a device to test the integration. Please note that you will not be able to see Upsight content from the Xcode simulator. You must test from a physical device in order to see content.

Getting Started

Step 5 Integration Checklist


To help make the integration process easier, we've created a checklist with troubleshooting tips that you can follow. If you are not getting expected results after integration, consults the checklist to see if there are any steps that you are missing.

Integration Checklist

Content Unit Types

Anouncements


Announcements are messages delivered to players in your app. Use the Upsight Dashboard to set up an announcement. No additional code is required.

Content Unit Types

Internal Cross-Promotions


Internal Cross-Promotions are customizable promotions for your own apps. See Help Center overview for more information. No additional code is required.

Content Unit Types

More Games Widget


Upsight’s More Games Widget displays specific apps that you decide to promote. Use the Upsight Dashboard to determine which apps are being displayed in your More Games Widget. No additional code is required for a basic More Game Widget.

Content Unit Types

Opt-In Data Collection


Opt-In Data Collection is an in-app promotion that gives players the option to provide you with valuable information like their email address, name, or age. Use the Upsight Dashboard to display an Opt-In Data Collection Content Unit in the same way that other Content Units are displayed. No additional code is required.

Content Unit Types

Rewards


Rewards are items you define that are given to your users using the Upsight infrastructure. Any content unit can contain a reward for your user. See Help Center overview for more information.

After a content unit with a reward is displayed, the SDK sends the request:unlockedReward message to your delegate passing a reward object to your application. The PHReward object passed through this method has the following helpful properties:

  • name - The name of your reward as configured through the dashboard.
  • quantity - An integer representing the quantity associated with the reward.
  • receipt - A unique identifier that is used to detect duplicate reward unlocks. Your app should ensure that each receipt is only unlocked once.

Your delegate message unlocking the reward might look like this:

- (void)request:(PHPublisherContentRequest *)request unlockedReward:(PHReward *)reward
{
    if([reward.name isEqualToString:@"yourRewardName"])
    {
        // Your code to unlock the reward goes here...
    }
}

Content Unit Types

Virtual Goods Promotion


A Virtual Goods Promotion is a full-display promotion used to increase in-app purchases.

If the Upsight servers are made aware that a given user has already purchased a non-consumable In-App Purchase item, it will not show Virtual Goods Promotion Content Units for that item to that user. This is to avoid showing the user a promotion for an item that they have already purchased.

You can use the Virtual Goods Promotion Content Unit to trigger In-App Purchase requests in your app. You must implement the following delegate method to get notified when In-App Purchase requests are triggered by VGPs:

- (void)request:(PHPublisherContentRequest *)request makePurchase:(PHPurchase *)purchase;

The PHPurchase object passed through this method contains the following properties:

  • productIdentifier - The product identifier for your purchase. This is a unique string used for Store Kit requests.
  • quantity - An integer representing the quantity associated with the purchase.
  • receipt - A unique identifier.

You are responsible for making an SKProductRequest as well as creating a SKPayment object and adding it to a payment queue to initiate the purchase, for complete information see In-App Purchase Programming Guide.

Note In earlier versions of Upsight, you had to call - [PHPurchase reportResolution:] to dismiss the Virtual Goods Promotion content unit. You no longer have to do this.

Push Notifications


To get started with Push Notifications, read our Push Notifications Overview page. For more information on the implementation portion of Push for iOS, read our iOS Push Notification Guide

Advanced

Preloading


To make content requests more responsive, you may choose to preload a content unit for a given placement. This starts a request for a content unit without displaying it, preserving the content unit until you call - (void)send on a content request for the same placement in your app.

[[PHPublisherContentRequest requestForApp:(NSString *)token
secret:(NSString *)secret
placement:(NSString *)placement
delegate:(id)delegate] preload];

You may set a delegate for your preload if you would like to be informed when a content request is ready to display. The next section provides more details.

WARNING If you are preloading multiple different placements that display the same content unit, frequency caps for this content unit may not be applied.

If you are not concerned about frequency capping, preloading can speed up the ad display and improve the consumer experience.

Advanced

Checking Console Logs


To check Console logs for iOS devices use Apple’s iPhone Configuration Utility. It can be downloaded online directly from Apple (Windows, Mac). Hook your device up to your computer via USB cable, run iPhone Configuration Utility, open the device in the utility, and click the Console tab.

Advanced

COPPA


If you operate a mobile app directed to children under 13 that collects, uses, or discloses personal information from children or you otherwise have actual knowledge that you are collecting, using, or disclosing personal information from children under 13, the Children’s Online Privacy Protection Act (COPPA) may apply to you. If so, you may have responsibilities relating to how you collect, disclose, or use personal information from such children.

To assist you in your data collection, disclosure and use compliance obligations, we have added to the platform a new "opt-out" setting to the iOS SDK, so you can indicate whether you want Upsight to limit data collection and use, and serve only contextually targeted ads.

Child-directed settings and features

  • A default value for the opt-out flag in the SDK that can be changed by the publisher. The default value out-of-the-box will be Opt-Out = FALSE.
  • Functionality in the SDK to change the opt-out flag for the individual user. Publisher may use this setting if it utilizes age-gating functionality, for example.

WARNING It is extremely important to understand the consequences of setting the opt-out status to TRUE. By setting the opt-out status to TRUE, advertising will be limited to only contextual ads and platform data collection capabilities will be disabled. Currently, our platform only supports behavioral advertising. In the short-term, this means that when opt-out is set to TRUE, no Upsight-served ads will be available to your apps.

Example

If you have an app that is directed at 8-10 year olds, you can set the default value for the opt-out flag to be TRUE for all users. Then, you can add an age-gating mechanism to the app, and change the opt-out flag to FALSE for users that you learn to be 13 or older.

Targeting Opt-Out

To comply with COPPA regulations and standards, Upsight has provided a mechanism for your app to opt-out of collecting user information. The user opt-out status inside your app is indicated by

+ [PHAPIRequest optOutStatus]

Its value defaults to NO, which means that user data is sent by default. Adding the PHDefaultUserIsOptedOut key with a Boolean value in your app's information property list file will change the default value. If PHDefaultUserIsOptedOut is set to YES, then + [PHAPIRequest optOutStatus] also defaults to YES, otherwise the default value is NO.

The ability to change default behaviour in advance can be useful for publishers who create apps targeted at an expected underage audience.

To set the opt-out status for your app on an individual basis at runtime, use the following method:

+ [PHAPIRequest setOptOutStatus:(BOOL)yesOrNo];

Although Upsight has enabled this functionality, you are still responsible for providing an appropriate user interface for user opt-out. Note, setting opt-out status using this method overrides the default value that is set with the PHDefaultUserIsOptedOut key.

For official information about COPPA, the recent amendments, and a list of FAQs provided by the FTC, please consult the FTC website.

Advanced

Content Request Delegate Methods


Overview

Once you start a content request, there are a series of delegate methods that are called by the Upsight SDK at various points in the process of requesting, downloading, displaying, and dismissing an Upsight content unit. You are not required to implement these delegate methods, but by doing so, your app can take various actions in response to the progress of the Upsight content request.

Will Get Content

The Will Get Content delegate method is called right before the SDK makes a content request.

- (void)requestWillGetContent:(PHPublisherContentRequest *)request;

Did Get Content

The Did Get Content delegate method is called when the SDK starts to receive valid content from Upsight servers. This will be the last delegate method a preloading request will receive unless there is an error.

- (void)requestDidGetContent:(PHPublisherContentRequest *)request;

Content Will Display

The Content Will Display delegate method is called when content for this placement (if any) has been loaded. Depending on the transition type for your content, your view may or may not be visible at this time. This method is a good place to pause any animations in your app.

- (void)request:(PHPublisherContentRequest *)request contentWillDisplay:(PHContent *)content;

Content Did Display

The Content Did Display delegate method is called when the content unit has been shown and a user is able to interact with the displayed content view.

- (void)request:(PHPublisherContentRequest *)request contentDidDisplay:(PHContent *)content;

Content Did Dismiss With Type

The Content Did Dismiss With Type delegate method is called when the content has been dismissed and control is being returned to your app. This can happen as a result of the user clicking on the close button or clicking on a link that will open outside of the app. If you have paused animations, then you can restore animations when this method is called.

- (void)request:PHPublisherContentRequest *)request contentDidDismissWithType:(PHPublisherContentDismissType *)type;

The type argument will be one of the following constants:

  • PHPublisherContentUnitTriggeredDismiss - The user or a content unit dismissed the content request.
  • PHPublisherNativeCloseButtonTriggeredDismiss - The user used the native close button to dismiss the view.
  • PHPublisherApplicationBackgroundTriggeredDismiss - The content unit was dismissed because the app was sent to the background.
  • PHPublisherNoContentTriggeredDismiss - The content unit was dismissed because there was no content assigned to this placement ID.

Advanced

Custom Dimensions for Targeting


Custom Dimensions provide the ability to target marketing campaigns towards a customized segment of users.

Important Custom Dimensions must be created in the Upsight Marketing Dashboard before they can be integrated in the SDK. This document provides more information on creating Custom Dimensions.

To add custom dimensions to any content request, use the addDimensionsFromDictionary convenience method. This method takes an input parameter of type NSDictionary. The dictionary keys must be of type NSString and the values must be NSString, NSNumber, or NSNull.

Upsight stores all custom dimensions received from the SDK on the server for each device using your app.

The keys that you use in the SDK must match the keys created in the Upsight Marketing Dashboard.

Sending the same key with a different value for a device will update the custom dimension stored on the server.

Sending a key with an NSNull value for a device will delete the custom dimension stored on the server.

The following code adds custom dimensions to a content request.

// Create a content request
PHPublisherContentRequest *request = [PHPublisherContentRequest
requestForApp:@"YOUR_APP_TOKEN"
secret:@"YOUR_APP_SECRET"
placement:@"app_launch"
delegate:self];

//Add custom dimensions to the request
[request addDimensionsFromDictionary:@{@"gold_balance":@(2170),
@"ua_source":@"PlayHaven", @"registered":@(YES)}];
[request send];

Advanced

Custom Events for Analytics


Send custom events when a user performs an action specific to your application. This action can be anything that you deem valuable to track, such as progression to another level in a game.

To send a custom event, create a PHEvent object with a dictionary representing the event properties you wish to track. The dictionary has the following restrictions:

  • The keys must be strings and the values must be either: NSString, NSDictionary, or NSNumber.
  • The dictionary size must be less than 100 KB.

It is important to note that the dictionary must conform to a specific structure in order for your events to be tracked correctly. Please use the Upsight Event Designer to construct your event data.

The Event Designer will also generate code for you to use, as shown below. This sample code sends the PHEvent object using the PHEventRequest class.

PHEvent *theEvent = [PHEvent eventWithProperties:@{@"inventory" : @{@"swords" :@{@"katanas" : @(3)}}}];
PHEventRequest *theRequest = [PHEventRequest requestForApp:@"YOUR_APPLICATION_TOKEN" secret:@"YOUR_APPLICATION_SECRET" event:theEvent];

// Optionally assign a delegate to the request object to get notified when it succeeds/fails
theRequest.delegate = self;

[theRequest send];

Advanced

Finding Device Identifiers


How to find your IDFA

The easiest way to get a device's IDFA is by checking your console log while opening your app that is integrated with the Upsight SDK.

  1. Connect your device to your computer via USB cable.
  2. Check the console log on your computer. To learn how to check the console log, see the iOS console logs article.
  3. Open the app that you have integrated the Upsight SDK with.
  4. Search for d_ifa= in the console log.

Here's an example of the d_ifa= parameter from an Upsight open call:

http://api2.playhaven.com/v3/publisher/open/?tz=-7.0&scount=2&scale=2&connection=2&width=320&plugin=ios&opt_out=0&sig4=cLpywmzy3iioIOx_NlibB6ALHHY&languages=en&d_ifa=236A005B-700F-4889-B9CE-999EAB2B605D&token=881e542582b24001a5ddb87323c49695&os=iPhone+OS+7.1.1&idfv=C305F2DB-56FC-404F-B6C1-BC52E0B680D8&ssum=0&idiom=0&nonce=Qt21GhcYf6AwWq1bxJWwvRyKJSg&app_version=1.0&tracking=1&sdk-ios=1.23.0&hardware=iPod5%2C1&app=com.upsight.iOS-Test&height=548

By searching for the d_ifa= parameter in the console log, you can find the IDFA. In the example above, the IDFA is 236A005B-700F-4889-B9CE-999EAB2B605D.

Note If the "Limit Ad Tracking" setting in Settings-> Privacy->Advertising is on, Upsight will ignore the IDFA sent, which effectively means the device will be unrecognizable to Upsight (i.e. it will be treated as a new device, it will not act as a test device even if it is registered as a test device with the proper IDFA, no user activity will be tracked, etc.)

You can also reset your IDFA from this screen. If you do a full hardware reset on your device, your IDFA will be reset to something else.

How to find your IDFV

The easiest way to get a device's IDFV is by checking your console log while opening your app that is integrated with the Upsight SDK.

  1. Connect your device to your computer via USB cable.
  2. Check the console log on your computer. To learn how to check the console log, see the iOS console logs article.
  3. Open the app that you have integrated the Upsight SDK with.
  4. Search for idfv= in the console log.

Here's an example of the idfv= parameter from an Upsight open call:

http://api2.playhaven.com/v3/publisher/open/?tz=-7.0&scount=2&scale=2&connection=2&width=320&plugin=ios&opt_out=0&sig4=cLpywmzy3iioIOx_NlibB6ALHHY&languages=en&token=881e542582b24001a5ddb87323c49695&os=iPhone+OS+7.1.1&idfv=C305F2DB-56FC-404F-B6C1-BC52E0B680D8&ssum=0&idiom=0&nonce=Qt21GhcYf6AwWq1bxJWwvRyKJSg&app_version=1.0&tracking=1&sdk-ios=1.23.0&hardware=iPod5%2C1&app=com.upsight.iOS-Test&height=548

By searching for the idfv= parameter in the console log, you can find the IDFV. In the example above, the IDFV is C305F2DB-56FC-404F-B6C1-BC52E0B680D8.

Advanced

In-App Purchase Tracking


All in-app purchases made by users in your app should be tracked by using Upsight's IAP tracking calls. You should do this for all purchases, regardless of whether Upsight Virtual Goods Promotions triggered these purchases. By providing data on your in-app purchases to Upsight, you can track your users' overall lifetime value, as well as track conversions from your Virtual Goods Promotion content units. This is completed using the PHPublisherIAPTrackingRequest class.

To report successful purchases, use the following code either in your SKPaymentQueueObserver instance or after a purchase has been successfully delivered:

PHPublisherIAPTrackingRequest *request = [PHPublisherIAPTrackingRequest requestForApp:token
    secret:secret
    product:productID
    quantity:itemsQuantity
    resolution:PHPurchaseResolutionBuy
    receiptData:transactionReceipt];
[request send];

Important Please only use receipts from SKPaymentTransaction, Upsight currently does not support receipts from any other method.

Purchases that are canceled or encounter errors should be reported using the following:

PHPublisherIAPTrackingRequest *request = [PHPublisherIAPTrackingRequest requestForApp:token
    secret:secret
    product:productID
    quantity:itemsQuantity
    error:error
    receiptData:nil];
[request send];

If the error comes from an SKPaymentTransaction instance's error property, the SDK automatically selects the correct resolution (buy/cancel) based on the NSError object that is passed in.

Note If you are funnelling your data from the Upsight SDK into the Upsight Analytics Dashboard, do not send both Monetization messages through the Upsight Enterprise SDK and In-App Purchase Tracking through the Upsight SDK. Doing so will cause double-counting in your purchase data. To ensure your purchase data is accurate, if you are using both the Upsight SDK and the Upsight Enterprise SDK, only send in-app purchase tracking through the Upsight SDK, not both.

Purchase Receipt Validation

You can now send purchase receipt data to the Upsight server to verify purchases against Apple receipts to insure that only valid purchases are being reported. To verify that a purchase is valid, add the receipt data from the In-App Purchase to the IAP tracking request by using the receiptData argument to the method.

Advanced

More Games Widget Notification View


The More Games Widget supports the creation of a notification that allows a user to see when there are new apps. To create a notification view, create a PHNotificationView object with your app’s Token and Secret. Then add the PHNotificationView object as a subview to your controller’s view and then run the -[PHNotificationView release] method.

PHNotificationView *notificationView = [[PHNotificationView alloc] initWithApp:MYTOKEN secret:MYSECRET placement:@"more_games"];
[myView addSubview:notificationView];
[notificationView release];

This will create a little badge, a little number in a red circle that appears on top of a More Games button in your user interface. These badges will remain anchored to the center of the position they are placed, even as the size of the badge changes. To adjust the position of the badge, set the center property.

notificationView.center = CGPointMake(10,10);

The PHNotificationView object will query and update when its - [PHNotificationView refresh] method is called. We recommend that the notification view each time it appears in your user interface. For an example, see the examples/PublisherContentViewController.m file.

Be sure to clear any notification view instances when you successfully launch a content unit. This can be done by calling the - [PHNotificationvView clear] method on any notification views that you wish to clear.

[notificationView.clear];