Upsight logo Back to top

Advanced

Content Display Options


By default, the SDK shows a brief loading screen before displaying content. FullScreen content units can take a third parameter that controls the display of the loading overlay in the SDK.

Example:

This content request will show the placement attached to "content_example" with no loading screen:

startActivity(FullScreen.createIntent(this, "content_example", PlayHavenView.NO_DISPLAY_OPTIONS));

Settings:

NO_DISPLAY_OPTIONS

If you specify NO_DISPLAY_OPTIONS, no additional indicators will be added.

DISPLAY_OVERLAY

If you specify DISPLAY_OVERLAY only, a partially transparent overlay will be added until the content is ready to be displayed.

enter image description here

DISPLAY_ANIMATION

If you specify DISPLAY_ANIMATION only, an indeterminate progress indicator will be shown until the content is ready to be displayed.

enter image description here

DISPLAY_OVERLAY | DISPLAY_ANIMATION

If you “or” the DISPLAY_OVERLAY and DISPLAY_ANIMATION flags together, both the overlay and progress indicator will be displayed.

enter image description here

AUTO_DISPLAY_OPTIONS

If you specify AUTO_DISPLAY_OPTIONS, the system will intelligently determine what is best for viewing.

Content Result


Making a Content Request with the startActivityForResult method instead of the startActivity method allows you to send a unique ID that you can check for in the onActivityResult callback. This allows you to use the same method for multiple requests. The id you choose is arbitrary as long as it is unique.

private static final int EXAMPLE_REWARD_ID = 10001;
private static final int EXAMPLE_IAP_ID = 10002;

As a reminder, this is what a regular startActivity method looks like.

startActivity(Intent)

To send the unique ID, we replace it with the startActivityForResult method.

startActivityForResult(Intent, Unique_ID)

So, our request will now look like this.

startActivityForResult(FullScreen.createIntent(this, "placement_tag"), EXAMPLE_REWARD_ID);

Now that we will get a callback, we can implement it. Because the callback will be passing an ID, we can ignore anything that does not have the unique ID we are passing.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data){
  if(requestCode != EXAMPLE_REWARD_ID)
      return;

  String placementTag = data.getStringExtra(PlayHavenView.BUNDLE_PLACEMENT_TAG);
  PlayHavenView.DismissType dismissType = (PlayHavenView.DismissType) data.getSerializableExtra(PlayHavenView.BUNDLE_DISMISS_TYPE);
  Toast.makeText(this, placementTag + " was dismissed: " + dismissType, Toast.LENGTH_LONG).show();
}

Content results are used in content types that collect data. This includes like Rewards, In-App Purchases, and Opt-In Data Collection.

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 (to be available in our upcoming server-side update) a new “opt-out“ setting to the Android 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

PlayHaven.getOptOut(Context context)
PlayHaven.setOptOut(Context context, boolean setting)

The default opt-out status is set to FALSE. If you need to opt-out of collecting user information, simply call setOptOut and set the value to TRUE.

Note Although Upsight has enabled this function, you are still responsible for providing an appropriate user interface for user opt-out.

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

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 a placement, you must implement preloading. Create a Placement object and add custom dimensions to it using the addDimension method, which takes a key and value as input. The key must be a String, and the value must be either a String, Number, boolean, or null.

  • 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 a null 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 new placement
Placement placement = new Placement("app_launch");

// Add dimensions before preloading the placement
placement.addDimension("gold_balance", 2170);
placement.addDimension("ua_source", "PlayHaven");
placement.addDimension("registered", true);

// Preload the placement
placement.preload(myContext);

You can also add custom dimensions in bulk by passing in a HashMap to the addDimensions method, as shown below.

// Create HashMap of custom dimensions
HashMap<String,Object> dimensions = new HashMap<String,Object>();
dimensions.put("gold_balance", 2170);
dimensions.put("ua_source", "PlayHaven");
dimensions.put("registered", true);

// Create a new placement
Placement placement = new Placement("app_launch");

// Add dimensions before preloading the placement
placement.addDimensions(dimensions);

// Preload the placement
placement.preload(myContext);

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 CustomEvent object with data in JSON format representing the event properties you wish to track. The dictionary has the following restrictions:

  • The data must be properly formatted JSON.
  • The data size must be less than 100 KB.

It is important to note that the JSON data 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 CustomEvent object using the CustomEventRequest class.

try{
// Create an event with raw JSON string, JSON object, Reader, etc
CustomEvent event = new CustomEvent(
"{\"inventory\":{\"swords\":{\"katanas\":3}}}");

// Create the server request
request = new CustomEventRequest(event);

// If you would like to be notified of success/failure
request.setResponseHandler(this);

// Send via your Context
request.send(this);
}catch (PlayHavenException e){
Log.e(TAG, "Error sending custom event", e);
}

Finding Device Identifiers

How to find your Android ID


Using logcat

  1. Connect your device to your computer via USB cable.
  2. Check the console log on your computer. You can do this via logcat
  3. Open the app that you have integrated the Upsight SDK with.
  4. Search for device= in the logs.

Here is an example of the device parameter from an Upsight open call:

http://api2.playhaven.com/v3/publisher/open/?app=com.example.app&opt_out=0&app_version=unknown&os=19&hardware=Nexus%207&connection=2&idiom=2&width=557&height=320&sdk_version=2.2.2&plugin=android&languages=en_US,en&token=8267a715ecff4abcbfdd281aebeec522&device=bedb0ff7a69ddf5b&dpi=160&nonce=pQApYr1Cy-HPNCJ_8P7d1Wa6-z0&sid=2058006879690356691&sig4=kZzHIXJ4OMDgq1uzc_UO7xtnojk&tz=-7.00&scount=1&ssum=0

By searching for the device parameter in the console log, you can find the Android ID. In the example above, the Android ID is bedb0ff7a69ddf5b.

Using an App

  1. Download the free app, Android System Info, from Google Play
  2. Visit the 'System' tab at the top.
  3. Look for the Android ID listed in the OS subsection.

In-App Purchase Tracking


You can use the Upsight SDK to track In-App Purchases (IAP) using a Virtual Goods Promotion (VGP) content unit defined in the Upsight Dashboard or from your own data. Using a VGP, if the user chooses to buy a product displayed, the product SKU is sent to your code so that you may initiate the purchase. Once the IAP has been resolved (bought, cancelled, error, etc.), you must notify Upsight using a PurchaseTrackingRequest call. You are then able to further refine your User Segmentation in the Upsight Dashboard based on the Amount Spent.

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.

To track an In-App Purchase in your application, you must have the IAP product in your dashboard. Then you can add the following to your Android app code:

  • Create a PurchaseTrackingRequest object from your Purchase object.
  • Use the object's send method to send the purchase to Upsight.

In the following example we write a reusable method called track that tracks a purchase attempt.

/**
 * Unique name for logging
 */
private static final String TAG = IAPTrackingExample.class.getSimpleName();

/**
 * For creating fake orderId and payload
 */
private static final Random random = new Random(new Date().getTime());

private void track(View target, Double price, Purchase.Result result)
{
  Purchase purchase = new Purchase();
  purchase.setSKU(getResources().getResourceName(target.getId()));
  purchase.setPrice(price);
  purchase.setStore("OurCoolStore");
  String orderId = random.nextLong() + "ABC";
  purchase.setPayload(TAG + ":" + orderId);
  purchase.setOrderId(orderId);
  purchase.setQuantity(1);
  purchase.setResult(result);
  (new PurchaseTrackingRequest(purchase)).send(this);
}

If the IAP resolves as bought, we can use the Purchase.Result.Bought result to inform the server that this particular product has been purchased successfully.

track(target, 1.50, Purchase.Result.Bought);

If the IAP resolves as already purchased, most stores will not allow the item to be purchased again. You can use the Purchase.Result.Owned result to inform the server that the item was not purchased again.

track(target, 10.00, Purchase.Result.Owned);

If the item the user is asking for no longer exists, you can use the Purchase.Result.Invalid result. This can happen if the item was disabled on the server side but the user has not upgraded their app.

track(target, 5.00, Purchase.Result.Invalid);

If the transaction has been cancelled, you can use the Purchase.Result.Cancelled result.

track(target, 1.00, Purchase.Result.Cancelled);

If the transaction returns an error, you can use the Purchase.Result.Error result.

track(target, 2.00, Purchase.Result.Error);