Upsight logo Back to top

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.

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.

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.

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.

Content Request Delegate Methods

Will Get Content


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

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

Content Request Delegate Methods

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 Request Delegate Methods

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 Request Delegate Methods

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 Request Delegate Methods

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.

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];

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];

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.

Finding Device Identifiers

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.

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.

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];