Native inline content messages

Data format

Native messages have to be understood by the mobile or web application, so it is important to define the data format first. Any updates to the style or the content options of native messages are going to require an app/site update.

The format of the data is completely up to the customer, but a typical example would be:

{
  "type": "announcement",
  "title": "Free 10 EUR bet",
  "text": "Participate and earn a free 10 EUR bet",
  "icon": "bet",
  "style": {
    "color": "red"
  }
}

📘

Type field

We recommend introducing a field like type in order to be able to add more types of messages in future if needed.

Android integration

## Implement the new NativeInappListener Interface

public class YOUR_APPLICATION extends Application implements NativeInappListener

Add the reference to the pushConnector.builder config

new PushConnector.Builder(XPUSH_APP_KEY, GOOGLE_PROJECT_NUMBER)
	.setNativeInappListener(this)
	.create(this)

Implement native in-app message handler

This is where you should parse the data and build your native in-app message element. Note, you can either present the message to a user straight away, or you can store it until the user navigates to a certain section of the app where a message should be presented (see triggering & placement section for more details).

@Override
public void nativeInappReceived(Message xpMessage) {
    // called when message received from the server
}

Your custom data will come in the inapp_data payload as a JSON string. Here is an example of accessing and parsing the data:

String data = xpMessage.data.get("inapp_data");
// Parse JSON example

Report a delivery when an Android message is presented to a user

When a message is presented to the user we recommend tracking it with Xtremepush platform so you can keep track of how many times messages were shown in the analytics.

mPushConnector.reportMessageDelivered(xpMessage);

📘

Note on preloading content

This method doesn’t have to be called immediately after receiving a message in the handler. It is a common approach to pre-load the list of in-app messages on the application start and only report the delivery when the user navigates to a certain section in the app and the message is finally presented.

Report a click when a user interacts with an Android message

mPushConnector.reportMessageClicked(xpMessage, null);

In case the message allows multiple different actions - you can specify which one was taken by passing a button ID / action ID as a second parameter:

mPushConnector.reportMessageClicked(xpMessage, "accept");

iOS integration

## Implement native in-app message handler

This is where you should parse the data and build your native inapp message element. Note, you can either present the message to a user straight away, or you can store it until the user navigates to a certain section of the app where a message should be presented (see triggering & placement section for more details).

XPush.registerNativeMessageHandler { [weak self] message in
    // called when message received from the server
}

Your custom data will come in the inapp_data payload as a JSON string. Here is an example of accessing and parsing the data:

let data = message.payload["inapp_data"] as? String
// Parse JSON from data

Report a delivery when an iOS message is presented to a user

When a message is presented to the user we recommend tracking it with Xtremepush platform so you can keep track of how many times messages were shown in the analytics.

XPush.reportMessageDelivered(message)

📘

Note on preloading content

This method doesn’t have to be called immediately after receiving a message in the handler. It is a common approach to pre-load the list of in-app messages on the application start and only report the delivery when the user navigates to a certain section in the app and the message is finally presented.

Report a click when a user interacts with an iOS message

XPush.reportMessageClicked(message)

In case the message allows multiple different actions - you can specify which one was taken by passing a button ID / action ID as a second parameter:

XPush.reportMessageClicked(message, "accept")

Web integration

With the function on native_onsite, the syntax to intercept the content and do something with it is as follows:

xtremepush('on','native_onsite', function(data) {
 console.log('your data is');
 alert(JSON.stringify(data));
});

This function returns the data object with the parameters that you have provided within the Native message, such as RAW or JSON parameters.

You will need to use the JSON.stringify function/method to convert the returned data into String and once that has been executed, the end user can handle the message as expected.

For example, if you are passing down key/value pairs such as "apples":"oranges", then this will be returned - and within the xpush function on native_onsite, you can modify it to for example include the content of the key/value pairs such as:

if(JSON.stringify(data).contains('apples')){
  console.log('this user is interested in apples');
}

Report a delivery when a web message is displayed to a user

//mark message delivered
 xtremepush('message', 'delivered', action_id, context);
 e.g.
 xtremepush('message', 'delivered', '12', {"apples":"oranges"});

Report a click when a user interacts with a web message

//mark message opened
 xtremepush('message', 'opened', action_id, 'context');
 e.g.
 xtremepush('message', 'opened', '12', {"apples":"oranges"})

Triggering & placement

There are two ways native messages can be triggered and presented:

• Load all messages on app open (using Session_Start Event) and present when needed.
• Load messages for individual app or web screens as user navigates between them (using custom events), and presented immediately upon receipt.

We would typically recommend to go with the first approach if possible as it means, that:

• Messages could be presented instantaneously when the user navigates around (because they are already stored on the app side and there is no need to load them from the server).
• Less events needed (a single session start event is sufficient to load all the messages).

Introduce a placement field in you data format

❗️

Communication with marketer

The following information should be communicated to your marketer who will need to make sure they include any expected values in their campaign setup. More details about setup can be found in the user guide under In-App native inline content campaign.

This field will be used to tell the application where to present the message.

For example you could have a simple screen field:

{
  "type": "announcement",
  "title": "Free 10 EUR bet",
  "text": "Participate and earn a free 10 EUR bet",
  "icon":" bet",
  "style": {
    "color": "red"
  },
  "screen": "football"
}

Or you could have a more complex version with multiple placements if needed:

{
  "type": "announcement",
  "title": "Free 10 EUR bet",
  "text": "Participate and earn a free 10 EUR bet",
  "icon": "bet",
  "style": {
    "color": "red"
  },
  "placements": [
    {
      "screen": "scores",
      "sport": "football"
    },
    {
      "screen": "favourites"
    }
  ]
}

Handle different placement options in the app

It’s up for a customer to decide on the format of the placement fields, but mobile apps need to know how to handle all those cases.

After receiving a message in the native in-app handler it should be stored within the application and presented to a user whenever they navigate to a certain screen.

Campaign stats

Once the message is presented it should be reported as delivered using reportMessageDelivery method described in the section above.

The different stats we track in order for you to understand in-app message performance:

• Sent: number of messages sent from the platform to the device into the custom handler function
• Delivered: number of messages actually shown to the user (it is important to have reportMessageDelivery method called in the app)
• Clicked: number of messages clicked by the user (it is important to have reportMessageClick method called in the app)
• Click Rate: number of messages clicked vs number of messages delivered