Upsight logo Back to top

Native Messaging

Overview


Native Messaging lets you leverage Upsight’s Segmentation and Targeting to deliver campaigns where you can implement your own native display, instead of using one of Upsight’s interstitial campaigns.

Note Native Messaging is supported on Upsight SDK versions 4.4.0 and above.

Native Messaging campaigns are delivered through Milestones and Billboards as with our other campaigns types, plus your own handling of the returned data. See the Milestones and Billboards section for the core concepts, and the below instructions for the additional steps required to start using Native Messaging.

Native Messaging campaigns are designed to create native experiences by collecting the inputs required to build a desired experience then sending that data to the correct devices at the correct times. Before a Native Messaging campaign is published, the application source code will need to be updated to handle and/or display the expected payload inputs. Once a campaign has been triggered and a payload has been passed back, it is up to the developer to have the infrastructure in place to handle and display their intended experience. This responsibility includes using Upsight provided helper methods and objects to track events such as clicks and impressions, as well as controlling the destruction of campaign content.

The Upsight SDK provides several methods to access the data contained in a payload and will return native objects when possible. These accessor methods are made available through UpsightData objects. UpsightData objects are an Upsight created object type with numerous Native Messaging specific capabilities. When a Native Messaging campaign is triggered, a UpsightData object will be returned through a delegate method, where the developer can then access the contents of the UpsightData object and build their experience.

Important Images are handled differently than the other supported data types. Images sent in a Native Messaging campaign are pre-fetched and stored on disk in order to reduce latency when rendering an image once a milestone is triggered. Pre-fetched images are accessed via a file path and can be handled in your source code using a UpsightData.Image object along with the provided helper methods.

Integrate For Native Messaging


Receiving Data From a Native Messaging Campaign

To receive data from a Native Messaging Campaign, register a listener to the billboardDidReceiveDataEvent. Your listener will get invoked when a campaign with a native message payload is received and a billboard of the same scope is open. While the billboard itself will not render any content, it is still used to make the payload available.

UpsightManager.billboardDidRecieveDataEvent += myDataMethod

This method passes in an UpsightData object that you can use as indicated below.

void myDataMethod(UpsightData data) {

}

Accessing Content in a Native Messaging Campaign Object

UpsightData objects provide instance methods to access the different types of objects contained in the native message.

Accessor method signatures for payloads generated using the Basic input format:

public string GetString(string key);
public bool GetBool(string key);
public int GetInt(string key);
public float GetFloat(string key);
public Image GetImage(string key);
public Color GetColor(string key);

UpsightData.Image is an object that contains properties for the image's loaded-on-disk file path, width, and height. Please use this information to load the image into memory and display it as you see fit.

Native Messages created using the ‘Raw’ input method will can be accessed via the GetRawData() method. This method provides a string containing raw data in the same structure and format as entered in the campaign on the Upsight Dashboard.

public string GetRawData();

Important After the billboard containing the native message is dismissed, all data associated with the returned UpsightData object will be removed. For images, this means that the image on disk that is being referenced will be deleted. Please make a separate local copy of any images that you would like to persist past the life of the billboard.

Tracking User Interaction

Once the Native Messaging campaign is ready to be displayed to the user, the interaction the user has with the campaign can be tracked by calling various methods on your UpsightData object. The available methods are:

  1. RecordImpressionEvent() - Send this once the content of the campaign is rendered and displayed to the user.
  2. RecordClickEvent() - Send this if the user interacts with your campaign such as accepting a dialog prompt.
  3. RecordDismissEvent() - Send this once the campaign is no longer on screen.
  4. Destroy() - Send this once the payload is no longer needed, e.g. after the dismiss button has been pressed or after a user has performed the desired action. This method must be called to inform the SDK that the content interaction is finished.

Important If a campaign is not intended to be seen by users, simply call Destroy() on the payload once it has been processed by the application.

Example


Here is a sample implementation of a Native Messaging campaign used to render a native interstitial within an application.

In order to have this example display the campaign on a device, a Native Messaging campaign was created on the dashboard by with the following inputs:

example screenshot 1

As well, to handle the expected payload from the Native Messaging campaign, the below implementation was added to the application intended to render the campaign:

private void billboardDidReceiveDataEvent(UpsightData data)
{
    _upsightData = data;
    BackgroundPanel.color = data.GetColor("BGColor");
    ButtonText.text = data.GetString("BodyCopy");
    Texture2D offerTexture = new Texture2D(1, 1);
    offerTexture.LoadImage(File.ReadAllBytes(data.GetImage("OfferImage").ImagePath));
    OfferImage.sprite = Sprite.Create(offerTexture, new Rect(0, 0, offerTexture.width, offerTexture.height), Vector2.zero);
    Texture2D ornamentTexture = new Texture2D(1, 1);
    ornamentTexture.LoadImage(File.ReadAllBytes(data.GetImage("OrnamentImage").ImagePath));
    OrnamentImage.sprite = Sprite.Create(ornamentTexture, new Rect(0, 0, ornamentTexture.width, ornamentTexture.height), Vector2.zero);
    _showingNativeMessage = true;
    BackgroundPanel.gameObject.SetActive(true);
}
public void nativeMessageDismissed()
{
    BackgroundPanel.gameObject.SetActive(false);
    _showingNativeMessage = false;
    _upsightData.RecordClickEvent();
    _upsightData.RecordDismissEvent();
    _upsightData.Destroy();
    _upsightData = null;
}

When a user reaches the appropriate milestone your Native Messaging payload will be delivered to the device. If handled correctly by the source code, the campaign creative will render an experience like this:

example screenshot 2

Testing a Native Messaging Campaign


Once a native messaging campaign is configured in the dashboard and the application is set up to handle native messaging payloads simply trigger a milestone with the scope of the campaign and open a billboard. Depending on the implementation, the campaign should render and, when clicked, a content displayed, dismissed, and click should display in Upsight RealTime.