Upsight logo Back to top

Getting Started


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

Step 1 Add Upsight SDK to the Project

Download the SDK

Download the Upsight iOS SDK.

Step 1 Add Upsight SDK to the Project

Add the src Directory

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

Step 1 Add Upsight SDK to the 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.

Step 1 Add Upsight SDK to the Project

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.

Step 1 Add Upsight SDK to the Project

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

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

Step 1 Add Upsight SDK to the 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.

Step 1 Add Upsight SDK to the Project

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
Preprocessor Macros Not Used In Precompiled Headers

Step 1 Add Upsight SDK to the Project

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.

Step 1 Add Upsight SDK to the Project

Including Upsight Headers

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

#import "PlayHavenSDK.h"

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.

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"
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.

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.

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