Web In-App messages

Starting with the Leanplum JavaScript SDK 1.7.0, you can use our in-app or pop up message templates in your web applications. To start consuming these messages in the JS SDK, there is additional code you will need to add. This will allow you parallel functionality as our mobile sdks to display a popup and track message actions.

🚧

Missing functionality compared to other SDKs

The following functionality is not currently available in the JavaScript SDK.

• Triggering message based on User attribute changes (ie "User Attribute changes from x value to y value")
• Geo-fencing messages ("User enters / exits custom region")
• API for muting campaign messages (muteFutureMessagesOfSameKind method)

Handling Rich In-App messages

Rich in-app messages are messaging templates based in HTML5, which offers more ways of customizing your pop messages than our other in-app message templates. You can learn more about these messages at Rich interstitial message ].

To implement these messages on your client side, you can enable automatic display of rich in-app messages (Rich Interstitial, Banner and Star Rating) adding the below function to your project. This is available starting with Leanplum JavaScript SDK 1.8.0+.

Leanplum.enableRichInAppMessages(true);

Handling Native In-App messages

In our mobile SDKs, we have a number of native in-app or pop up message templates available out of the box which allow you to notify your user of any updates, offers or many other use cases on your end. To handle these in-app message templates, on the web client side, you will need to define each template in your JavaScript code for which type of message you want to show and track.

The following example shows how you can show and track one of our Confirm messages. To achieve this, we have created a listener for the showMessage native SDK event.

// 1. Register handler for in-app messages
Leanplum.on('showMessage', function (args) {
  var message = args.message;
  var context = args.context;
  
  // 2. Filter out unsupported message types
  if (message.__name__ !== 'Confirm') {
    return;
  }
  
  // 3. Track impression
  context.track();
  
  // 4. Show message and trigger attached actions
  //    (message needs to be customly rendered in HTML and actions can be called asynchronously)
  if (confirm(message.Message)) {
    context.runTrackedActionNamed('Accept action');
  } else {
    context.runTrackedActionNamed('Cancel action');
  }
});

Native In-app Message Types

There are six out-of-box templates in the Leanplum dashboard available also in your web application. Within each source code example, you will see the showMessage event function and is required to implement each type. The showMessage event arguments contains two objects:

• message - a Message object, specific to each type of message, as listed below
• context - an ActionContext object, which is used for tracking user actions and triggering actions

Additionally, each message has a __name__ field which indicates the type of message template to use (and the shape of the default JSON object). Below is a list of each type of message and an example of their JSON delivered to the client.

JSON
{
    __name__: "Confirm",

    Title: "Would you like to save $10?",
    Message: "This action cannot be undone.",
    "Accept text": "Yes",
    "Cancel text": "No"
}

JSON
{
    __name__: "Center Popup",    
Layout: {
        Height: 250,
        Width: 300
    },
    "Background color": "rgba(255,255,255,1)",
    "Background image": "",
    Title: {
        Color: "rgba(0,0,0,1)",
        Text: "Would you like to save 10%?"
    },
    Message: {
        Color: "rgba(0,0,0,1)",
        Text: "Use the code 'SAVE10' at checkout!"
    },
    "Accept button": {
        "Background color": "rgba(255,255,255,1)",
        Text: "Go to checkout",
        "Text color": "rgba(0,0,0,1)"
    }
}

JSON
{
    __name__: "Alert",

    Title: "Raffle entry successful.",
    Message: "You have entered our raffle!"
}

JSON
{
    __name__: "Web Interstitial",

    URL: "https://example.com",
    "Has dismiss button": true
}

JSON
{
    __name__: "Push Ask to Ask",

    Layout: {
        Height: 250,
        Width: 300
    },
    "Background color": "rgba(255,255,255,1)",
    "Background image": "",
​​​
    Title: {
        Color: "rgba(0,0,0,1)",
        Text: "LeanplumSample"
    },
    Message: {
        Color: "rgba(0,0,0,1)",
        Text: "Tap OK to receive important notifications from our app."
    },
    ​​​"Accept button": {
        "Background color": "rgba(255,255,255,1)",
        Text: "OK",
        "Text color": "rgba(0,0,0,1)"
    },
    "Cancel button": {
        "Background color": "rgba(255,255,255,1)",
        Text: "Remind me later",
        "Text color": "rgba(0,0,0,1)",
    }
}

JSON
{
    __name__: "Interstitial",

    "Background color": "rgba(255,255,255,1)",
    "Background image": "",

    Title: {
        Color: "rgba(0,0,0,1)",
        Text: "Interstitital Test"
    },
    Message: {
        Color: "rgba(0,0,0,1)",
        Text: "Interstitial Message Body"
    },
    "Accept button": {
        "Background color": "rgba(255,255,255,1)",
        Text: "Accept",
        "Text color": "rgba(0,0,0,1)"
    }
}

Invoking web application functions with Open URL actions

By default, the Leanplum dashboard uses an Open URL action within in-app messages. When users click one of the in-app message buttons, they navigate to a URL. This behavior allows you to use hashes to invoke functions within your application, keeping the application decoupled from the Leanplum integration.

// Open URL action: "#dashboard"

// application
window.addEventListener('hashchange', function(e) {
  if (location.hash === '#dashboard') {
    Application.showDashboard();
  }
}, false);

Starting with version 1.8.2, the Leanplum SDK gives full control to handling Open URL actions through the openUrl event. You can use this if you use client-side routing, need to open links in new tabs, or if you need to invoke a function without changing the URL in your application. This will also allow you to handle any mobile deep link schema within your application.

Leanplum.on('openUrl', function(e) {
  // prevent default open
  e.preventDefault();

  if (e.url.startsWith('myapp://')) {
    // pass to client-side router
    router.push(e.url.slice(8));
  } else {
    // open in new tab
    window.open(e.url, '_blank');
  }
});

Creating Custom In-App messages

Starting with version 1.9.0, the Leanplum JavaScript SDK allows you to create custom in-app messages that show up in the Leanplum dashboard. Define all available custom actions in code, then use a device in development mode to synchronize the templates to the dashboard by clicking sync button in Messages Composer in-app popup.

// Define the action name and fields that will show up in the Leanplum dashboard
Leanplum.defineAction({
  // name shown in the template picker
  name: 'Custom Popup',
  args: [
    // properties in message editor
    { name: 'Title',   type: 'string', value: 'Title placeholder' },
    { name: 'Content', type: 'string', value: 'Content placeholder' },
    { name: 'Image',   type: 'file',   value: '' },

    { name: 'Layout',  type: 'group',  value: [
      { name: 'Width',   type: 'number', value: 800 },
      { name: 'Height',  type: 'number', value: 600 }
    ] },

    { name: 'Dismiss action', type: 'action', value: '' }
  ]
});

// Define the action name and fields that will show up in the Leanplum dashboard
Leanplum.defineAction({
  // name shown in the template picker
  name: 'Custom Popup',
  args: [
    // properties in message editor
    { name: 'Title',   type: ActionParameterType.String, value: 'Title placeholder' },
    { name: 'Content', type: ActionParameterType.Text,   value: 'Content placeholder' },
    { name: 'Image',   type: ActionParameterType.File,   value: '' },

    { name: 'Layout',  type: ActionParameterType.Group,  value: [
      { name: 'Width',   type: ActionParameterType.Number, value: 800 },
      { name: 'Height',  type: ActionParameterType.Number, value: 600 }
    ] },

    { name: 'Dismiss action', type: ActionParameterType.Action, value: '' }
  ]
});

To render a custom in-app message, register a handler to the showMessage event and handle it like other native in-app messages:

// Render the action by processing the "showMessage" event
Leanplum.on('showMessage', function (args) {
  var message = args.message;
  var context = args.context;

  if (message.__name__ === 'Custom Popup') {
    // render popup and use context
  }
})

// Render the action by processing the "showMessage" event
Leanplum.on('showMessage', (args: RenderOptions) => {
  const { message, context } = args;

  if (message.__name__ === 'Custom Popup') {
    // render popup and use context
  }
})