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.

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.

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

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.

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,

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
}

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

SDK


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

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.