Apps

Content Priority View

Overview


When a user encounters a placement within the app, one or more content units may be assigned to that placement; however, only one content unit may be presented at that moment. The system will display the content unit at the top of the Priority List for that particular placement unless they do not meet the target rules/requirements for that content unit. There are several rules that may suppress a content unit from being displayed to a particular user, such as:

  • content unit is targeted to iPad but the user is on an iPhone
  • user has already encountered the content unit and exceeded the defined frequency cap(s)
  • cross-promoted app is already owned by the user

The system will default to the next content unit in the Priority View until it finds a content unit that can be displayed to the user. If none can be displayed, the app continues without hesitation.

Note Test devices ignore rules but abide by the Priority View settings.

Content Priority View

Prioritizing the Content Units


When a new content unit is created, it is assigned as the top priority for placements it's assigned to be default. To adjust priority, the publisher must:

  1. Navigate to the Priority View on the App Index page.

    Before a placement is selected

  2. Click on a placement.

    The placement level_up_1 is selected and has no content units assigned

    The search box can be used to filter placements displayed.

    Filtering to only show content units with 'level_up' in the name

  3. Drag and drop the content units to change the order. The earlier in the list a content unit appears, the higher its priority it will be.

    Dragging and dropping a placement

  4. The new priority will save immediately.

App Settings

Reward Items


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.

Create items in your app's code, define the Reward Item on the Upsight Dashboard, and then use In-App Purchase tracking to fully utilize Reward Items with the Upsight SDK.

For more information about using Rewards, see Rewards Content Unit

Note Granting Rewards require additional instrumentation to function properly, please see your platform's respective integration guide (iOS, Android) for more information on the steps required to implement rewards in your application.

  1. Log into your Upsight Marketing Dashboard.

  2. From the list of apps at the bottom of the screen, click your app.

  3. On the top right of the screen, click the app settings button.

  4. From the list of menu of settings on the right, click the Reward Items link.

  5. On the top right of the screen, click the add reward item button.

  6. In the Item Tag textbox, enter the name you would like to use for your Reward Item.

    Note This should be a unique string that represents unlockable content in your app and must be recognized within your app code.

  7. In the Description box, enter a meaningful description for your Reward Item.

  8. From the Supported App Versions dropboxes, indicate your supported app versions.

  9. Click the save button to save the button without publishing it.

  10. Click the publish button to begin sending your Content Unit to users.

App Settings

IAP Products


In-App Purchase (IAP) Products let you sell a variety of items directly within your app, including app currency, virtual goods, or other in-app content. Create items in your app's code, define the Reward Item on the Upsight Dashboard, and then use In-App Purchase tracking to fully utilize Reward Items with the Upsight SDK.

IAP Products are configured in iTunes Connect or Google Play, for their respective platforms, and added to the Marketing Dashboard. IAP Products are selected when creating a Virtual Good Promotion.

Note IAP Products require additional instrumentation to function properly, please see your platform's respective integration guide (iOS, Android) for more information on the steps required to implement Virtual Goods Promotions.

To add an IAP, follow these steps:

  1. Log into your Upsight Marketing Dashboard.

  2. From the list of apps at the bottom of the screen, click your app.

    List of apps

  3. On the top right of the screen, click the App Settings button.

    App Settings Button

  4. From the list of menu of settings on the right, click the IAP Products link

    List of Menu Settings

  5. On the top right of the screen, click the Add IAP Product button.

    Add IAP Product Button

  6. In the Product ID box, enter your Product ID from iTunes Connect or Google Play.

    Product ID Box

    Note The Product ID can be for a single item or a bundle created in iTunes Connect.

  7. In the Description box, enter a meaningful description for your IAP Product.

    Description Box

  8. From the Type radio boxes, select whether your IAP is consumable or non-consumable.

    Type Radio Boxes

    Note This must match what you have defined in iTunes Connect or Google Play.

    • Consumable IAP Products such as virtual currency, can be purchased an infinite number of times by a particular player.
    • Non-consumable IAP Products will be awarded to end users only if they do not already own it. Non-consumable items such as a sword, can only be purchased once.
  9. In the Price textbox, enter your IAP price tier.

    Price Textbox

    Note The selected Price Tier for this IAP Product must match what's defined in iTunes Connect or Google Play. The user will always be charged the iTunes Connect or Google Play price tier regardless of what is selected in the Upsight Marketing Dashboard.

  10. From the Cleared for Sale radio boxes, indicate if the item is cleared for sale or not.

    Cleared for Sale Radio Boxes

    IAP Products that are not cleared for sale cannot be advertised via Upsight Marketing Virtual Good Promotions.

    Note This must match what's defined in iTunes Connect or Google Play.

  11. From the Supported App Versions dropboxes, indic!ate your supported app versions.

    Supported App Versions Dropboxes

    Use this section if your IAP Product is only available in specific versions of your app.

    Note App versions can be added and managed in App Settings.

  12. Click the Save button.

    Save and cancel button

App Settings

App Versions


What are app versions?

App versions are specific releases of your application. By adding app versions to the Upsight Marketing dashboard, you will be able to target users on those versions when delivering content to them.

How do I add app versions?

  1. Log into your Upsight Marketing Dashboard.

  2. From the list of apps at the bottom of the screen, click your app.

    App List

  3. On the top right of the screen, click the App Settings button.

    App Settings Button

  4. From the list of menu settings on the right, click the App Versions link.

    App Versions Link

  5. On the top right of the screen click the add app version button.

    Add App Version Button

  6. In the Version Number textbox, enter the version number.

    Version Number Textbox

    Note This version number must match your app's Property List file (.plist). Version numbers are formatted as "major.minor" or "major.minor.subminor". (e.g. 1.5.3).

  7. In the Description textbox, enter a meaningful description

    Description Textbox

  8. Click the Save button.

    Save Button

App Settings

User Segments


What are User Segments?

The User Segments feature allows you to target specific users for your app based on dimensions you define and target. Saving different user segments and apply the defined segments to content, without having to redefine targeting parameters within each content. When you apply dimensions to a user segment, for example United States for Location or WiFi for Connection, users will have to match either all or any dimensions defined.

Note Currently, each dimension can only be used once per User Segment.

Note Test Devices do not adhere to targeting rules.

Create complex targeting rules using one or many dimensions. Each User Segment can be defined with Boolean Operators (AND/OR/NOT) and nested rules. Here's an example of a complex rule that targets users in North America that are not on an iPod Touch and have either used the app for at least 3 hours or 100 sessions.

Screenshot of rules in place

How do I create User Segments?

Note If a User Segment is edited, the modifications will be applied to any content unit that it is assigned to. Additionally, if a User Segment is deleted, targeting rules will no longer be applied to content units that use it.

  1. Log into your Upsight Marketing Dashboard.

  2. From the list of apps at the bottom of the screen, click your app.

    App List

  3. On the top right of the screen, click the App Settings button.

    App Settings Button

  4. From the list of menu settings on the right, click the User Segments link.

    User Segments Link

  5. On the top right of the screen, click the add segment button.

    Add Segment Button

  6. In the Segment Name textbox, enter your Segment Name.

    Segment Name Textbox

  7. In the Description textbox, enter a meaningful description for your segment.

    Description Textbox

  8. From the first Definition dropdown box choose:

    • All if a user must meet all the rules you define to be targeted by the User Segment.

    • Any if a user must meet at least one of the rules you define to be targeted by the User Segment.

    First Definition Textbox

  9. From the next Definition dropdown box choose the dimension you wish the rule to target.

    Second Definition Textbox

  10. Each dimension will then have a series of form inputs you can complete to define the rule.

    Form Inputs for Amount Spent Dimension

  11. Below the rules that you have defined, click the Plus Button (+) to add a new rule.

    Plus Button

  12. Below the rules that you have defined, click the Ellipses Button (...) to add a new rule with extra added nesting logic.

    Ellipses Button

  13. To the right of each rule, click the x button to remove a rule.

    X Button

  14. At the bottom of the screen, click the save button to save your rule.

    Save Button

How do I migrate from old targeting rules?

Publishers that have saved or published content units with the old targeting rules (before Boolean/nesting UI and saved user segments was available), must go through a migration flow when editing old content units. The original targeting rules appear on the page and the user is given the following two options if they wish to make any changes:

  1. Save as a User Segment: Save existing rules as a User Segment after giving it a name and description. They may optionally edit the rules before saving.

  2. Replace with Saved User Segment: Select an saved User Segment to replace existing rules.

Custom Dimensions

Overview


The Upsight platform provides the ability to target your campaigns to segments of users through user segmentation. By default you can target by a number of different methods, but there are many times when you may wish to provide your own data to Upsight so you can target sets of users based on criteria in your own systems.

Custom Dimensions

Use Cases


There are many ways you can use Custom Dimensions, but here are a few common use cases:

  • Attribution Source.

    If you keep track of what acquisition source you might want to target users by channel. For example, if you want to test out a new ad network you could buy a test set of installs and then target them with special campaigns within Upsight.

  • Targeting Churn Prone Users.

    If you have an analytics solution that identifies users who may be churn prone you can send them push messages with Rewards, Virtual Good Promotions, or Announcements encouraging them to re-engage with your app.

  • Cross Promotions.

    If you have a number of apps you may want to promote apps to users who don't have them installed. For example, if you have apps A, B, and C you may want to segment users in app A who don't have app B installed and promote app B, and for those who don't have app C installed promote app C.

There are many use cases for custom dimensions so please use your creativity, and feel free to reach out with any questions or unique scenarios.

Custom Dimensions

How do I create a Custom Dimension?


To create a custom dimension go to the Manage Custom Dimensions section of the dashboard:

  1. Log into your Upsight Marketing Dashboard.

  2. From the list of apps at the bottom of the screen, click your app.

    App List

  3. On the top right of the screen, click the App Settings button.

    App Settings

  4. From the list of menu settings on the right, click the Custom Dimensions link.

    App Settings Menu

  5. On the top right of the screen, click the add dimension button.

    Note Custom Dimensions are allocated to Pro and Enterprise customers. To add Custom Dimensions to your account, please contact your CSM or Upsight Support.

    Important Once you have added a custom dimension you cannot edit it, so please be careful!

    Add Dimensions Button

  6. In the Dimension Variable Name textbox, enter the name you would like your Custom Dimension to have.

    This is a key to your variable for use in the CSV uploader or API. This value can be comprised of letters, digits, or _, and will likely be a name like user_level or acquisition_channel.

    Dimension Variable Name Textbox

  7. In the Dimension Description textbox, enter a meaningful description of your Custom Dimension.

    Dimension Description Textbox

  8. From the Dimension Type dropdown menu, select the variable type you would like your Custom Dimension to have.

    The three available types are:

    • Number: Useful for storing a user level or any numeric data (numbers can be integers or decimals). Numeric dimensions support matching operations of equals (user_level = 10, for example) or a range (user_level is between 5 and 20, for example).​

    • String: Useful for storing text data, this data can be matched by is or is not (example: acquisition_channel is Upsight).

    • Boolean: Useful for storing true or false data, can match is true or is false (example: is_churn_prone is true).

    Dimension Type Dropdown Menu

  9. On the bottom of the screen, click the save button to save your Custom Dimension.

    Save Button

Custom Dimensions

How do I set data?


Once a dimension has been created you can send data to it via a server-to-server API , via SDK, or via a CSV uploader in the dashboard.

Format

Both the API and CSV uploader in the dashboard use the same CSV file, which has the format of

device_id,type_id,dimension_name
  • device_id is the IFA, IDFV, or Android ID of the device you'd like to store the dimension for. You can also use the Upsight SID.

  • type_id: One of ifa, idfv, sid or device. IFA, IDFV or SID are for iOS, and DEVICE or SID are for Android.

  • dimension_name: The name of your custom dimension. For example, user_level or virtual_currency.​

Example:

device_id,type_id,user_level
28033E33-DFB6-42D1-BCA9-E7E693669F4D,ifa,10
73BD7A17-A3B3-427A-91CF-8E27B41A6B8C,idfv,15

Valid Values

  • String - A string of text, up to n characters.
  • Number - A number for comparison, can be an integer or decimal.
  • Boolean - True or 1 will be set to true, everything else will be set to false.

Custom Dimensions

How do I delete a value?


To delete a value for a Custom Dimension, include it in an upload with a missing value. For example, this file will result in a user_level of 2.5 being set for IDFA 28033E33-DFB6-42D1-BCA9-E7E693669F4D, and user_level will be deleted for 73BD7A17-A3B3-427A-91CF-8E27B41A6B8C.

device_id,type_id,user_level
28033E33-DFB6-42D1-BCA9-E7E693669F4D,ifa,2.5
73BD7A17-A3B3-427A-91CF-8E27B41A6B8C,ifa,

Custom Dimensions

API


To upload a custom dimension you will need to first authenticate and obtain a identity token.

Protocol: https

Verb: POST

Host: api2.playhaven.com

Endpoint: /v2/account/auth

Arguments:

  • email: the Upsight username (same as dashboard)

  • password: the Upsight password (same as dashboard)

Example:

$ curl -d "email=user%40email.com&password=password" https://marketing-api.upsight.com/v2/account/auth
{
 "errobj": null,
 "response": {
  "identity_token": "a044daf377e84b9d88bd8083beb88c5a"
 },
 "error": null
}

As custom dimension files can be very large the custom dimension uploader uses a pull mechanism, so in order to upload custom dimension values you will need to either host the CSV file on a file server or use our S3 proxy host.

S3 Proxy Host

Please skip ahead to Custom Dimension Uploader if you are using your own file server.

First you must obtain a signed URL to upload your file to. To do this you must name your file and fetch a URL to upload to:

$ curl "https://marketing-api.upsight.com/v2/files/game/1/custom_dimensions/devices?auth=00000000000000000000000000000000"
{
 "response":
 { "signed_request": "https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/1/1396377260-aaaaaaaaaaaaaa-untitled?AWSAccessKeyId=yyyyyyyyyyyyyyyyyyyy&Expires=1396377560&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "url": "https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/1/1396377260-aaaaaaaaaaaaaa-untitled"
 },
 "error": null
}

Please note the auth value here is the identity_token value from the authentication API above, and the s3_object_name value is the filename you are going to upload. The response you obtain here contains the URL you will upload the file to (signed_request) in addition to the URL that the custom dimension uploader will use (url).

Now you will post your file to the URL you have just obtained:

$ curl -H "x-amz-acl:public-read"  -H "Content-Type: text/plain" -T "my-csv-file.csv"  -X PUT  "https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/1/1396377260-aaaaaaaaaaaaaa-untitled?AWSAccessKeyId=yyyyyyyyyyyyyyyyyyyy&Expires=1396377560&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$

To verify the upload you can fetch the file you just uploaded with the url value above:

$  curl "https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/1/1396377260-aaaaaaaaaaaaaa-untitled" ....

Custom Dimension Uploader

The custom dimension uploader takes a game id and a URL to a file to fetch a CSV with custom dimension values (see S3 Proxy Host if you want to use Upsight to host your CSV files), and fetches and processes the file with a batch job which you can process the status of.

Protocol: http

Verb: POST

Host: api2.playhaven.com

Endpoint: v3/upload/dimensions

Arguments:

  • auth: the auth token (obtained above)

  • game_id: the app you wish to upload the dimensions for

  • app_os: ios or android

  • url: URL of the file to fetch the CSV with custom dimension data from

Example:

$ curl -H "Content-length: 0" -X POST "http://api2.playhaven.com/v3/upload/dimensions?auth=3169cbb2fc6a455a9fad2ac1265ac7c4&game_id=1&app_os=ios&url=https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/upload/1/1391743256-MjQ5MzYzMjc0MQ-user_level_vals.csv?AWSAccessKeyId=AKIAIDVUYZHW7CXTDJ2A&Expires=1391743556&Signature=kl%2FkpOimFHx2hR%2Fyqko99fdleb0%3D"
{
 "errobj": null,
 "response": {
  "job": {
   "url": "https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/1/1391743256-MjQ5MzYzMjc0MQ-user_level_vals.csv?AWSAccessKeyId=AKIAIDVUYZHW7CXTDJ2A",
   "game_id": 1,
   "app_os": "ios",
   "job_id": 25811
  }
 },
 "error": null
}

Custom Dimension Upload Status

The result of the Custom Dimension Uploader request is a JSON object that contains a job id, and you can obtain status on this job upload: whether it's in progress, whether there were any errors, etc.

Protocol: http

Verb: GET

Host: api2.playhaven.com

Endpoint: /v3/upload/dimensions

Arguments:

  • auth: the auth token (obtained above)

  • game_id: the app you wish to upload the dimensions for

  • job_id: the upload job you would like to fetch status for

Example:

$ curl "http://api2.playhaven.com/v3/upload/dimensions?auth=3169cbb2fc6a455a9fad2ac1265ac7c4&job_id=25812&game_id=1"
{
 "errobj": null,
 "response": {
  "status": "completed",
  "count": 2,
  "job_id": 25812,
  "queue_name": "custom_dimension_job",
  "job": "{\"url\": \"https://playhaven-custom-dimensions-devices.s3.amazonaws.com/ph-custom-dimensions-devices/1/1391743256-MjQ5MzYzMjc0MQ-user_level_vals.csv?AWSAccessKeyId=AKIAIDVUYZHW7CXTDJ2A\", \"game_id\": 1, \"app_os\": \"ios\"}",
  "created_on": 1391743512,
  "result": "{\"errors\": 0, \"success\": 2}",
  "updated_on": 1391743512
 },
 "error": null
}

Custom Dimensions

CSV Upload


If you want to upload files with your custom dimension data manually you can do so using the Upsight dashboard.

To upload a file:

  1. Log into your Upsight Marketing Dashboard.

  2. From the list of apps at the bottom of the screen, click your app.

    App List

  3. On the top right of the screen, click the App Settings button.

    App Settings

  4. From the list of menu settings on the right, click the Custom Dimensions link.

    App Settings Menu

  5. Select Upload Values on any of the dimensions

    Note The format is exactly the same as above (as with the API).

    Upload Values Link

Custom Dimensions

SDK


For instructions on sending Custom Dimensions via the SDK, please see our SDK documentation here.

Custom Dimensions

Creating Segments from Custom Dimensions


Now that you have created a Custom Dimension and added data via the API, via SDK, or via the CSV upload in the dashboard you can now create a user segment to target users who match these Custom Dimension values.

Note Custom Dimensions can be used in conjunction with standard Upsight dimensions such as amount spent, last session date, language, or country to create laser-targeted slices of your user-base.

As an example, let's say you have created a Custom Dimension called acquisition_channel which represents what channel they were acquired from (the values are facebook, crosspromo, etc.). Now let's say you'd like to create a User Segment that identifies users who were acquired from Facebook and have purchased over $1 from you.

In the definition section select all from the drop-down next to "of the following rules are met", and from the rule box select amount spent, is greater than, 1 USD. Next click the + below it and add a second rule of custom - acquisition_channel, is, and facebook. This will match users who have the Custom Dimension acquisition_channel value of facebook and have spent over $1.

For more information on User Segments, see the User Segment section.

Placements


Placements are hooks within your app that can trigger Upsight content such as cross-promotions for your other apps or announcements. Placements can be added anywhere in your app. Here are a few examples:

  • App Launch
  • End of Level
  • After Unlocking an Achievement
  • On Button Click
  • Upon Character Collision
  • ...or any in-app event or user action so get creative!

To create a Placement in your app 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 app 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.
  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

Adding Content


Content Units are assigned on the Upsight Dashboard and linked to the Placements you place within your app. For more information about Content Units, please see the Content documentation.

Add an Internal Cross-Promotion Screen