Upsight logo Back to top

Native Messaging


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

In the source file in which you would like to access a Native Messaging payload, simply import the marketing module.

Implement the onData callback in your UpsightBillboard.Handler in order to access your Native Messaging payload. This method will get called when a campaign with a native message payload is received. While the billboard itself will not render any content, it is still used to make the payload available.

public void onData(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:

String getString(String tag);
Boolean getBoolean(String tag);
Integer getInt(String tag);
Float getFloat(String tag);
Color getColor(String tag);
Image getImage(String tag);

UpsightData.Color is an object that provides an RGB colorString in RRGGBBAA format, the integer representation of the colour in intValue. as well as a helper function toARGB to translate the string colorString to AARRGGBB format.

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 dictionary containing raw data in the same structure and format as entered in the campaign on the Upsight Dashboard.

JSONObject getRawData();

Important After the billboard containing the native message is destroyed, all data associated with the returned UpsightData will be removed. For UpsightData.Image objects, 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 USDataPayload object. The available methods are:

  1. void recordImpressionEvent(); - Send this once the content of the campaign is rendered and displayed to the user.
  2. void recordClickEvent(); - Send this if the user interacts with your campaign such as accepting a dialog prompt.
  3. void recordDismissEvent(); - Send this once the campaign is no longer on screen.
  4. void destroy(); - Send 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.


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 Activity intended to render the campaign:

private UpsightData mData = null;

private class NativeMessageHandler extends UpsightBillboardHandlers.DefaultHandler {

    public NativeMessageHandler(Activity activity) {

    public void onData(UpsightData data) {
        // Cache data payload.
        mData = data;

        // Show dialog fragment from data payload.
                .show(getFragmentManager(), "native_message_fragment");

    public void onDetach() {
        // Release data payload.
        mData = null;

public static class NativeMessageFragment extends DialogFragment {

    static NativeMessageFragment newInstance(String bodyCopy,
                                             int bgColorIntValue,
                                             String ornamentImagePath,
                                             String offerImagePath) {
        Bundle args = new Bundle();
        args.putString("bodyCopy", bodyCopy);
        args.putInt("bgColorIntValue", bgColorIntValue);
        args.putString("ornamentImagePath", ornamentImagePath);
        args.putString("offerImagePath", offerImagePath);

        NativeMessageFragment fragment = new NativeMessageFragment();
        return fragment;

    public Dialog onCreateDialog(Bundle savedInstanceState) {
        // Record impression event.
        final UpsightData data = getDataPayload();
        if (data != null) {

        // Create dialog from data payload.
        final Bundle args = getArguments();
        final View view = getActivity().getLayoutInflater()
                .inflate(R.layout.native_message_fragment, null);
        ((ImageView) view.findViewById(
        return new AlertDialog.Builder(getActivity())
                .setIcon(new BitmapDrawable(getResources(), args.getString("ornamentImagePath")))

    public void onDismiss(DialogInterface dialog) {

        // Record dismiss event and destroy.
        final UpsightData data = getDataPayload();
        if (data != null) {

    private UpsightData getDataPayload() {
        MyActivity activity = (MyActivity) getActivity();
        if (activity != null) {
            return activity.mData;
        return 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.