What are Push Primers

When a user opens your app for the first time, they are prompted with a push notification permission asking them to allow or deny notifications.

A push primer is a custom in-app message that appears before this push notification dialog, giving you the opportunity to explain the value of notifications to your users.

👍

Why use Push Primers

• A push primer lets you tell users what they will get from notifications like deals, order updates, live scores, before the push permission dialog appears.
• iOS and Android each allow only one native push notification permission prompt per app install. If a user declines, they won't be able to opt-in to notifications unless they change their device settings.

Configure a Push Primer Campaign

📘

Building Custom Push Primers

This section covers how to build push primers without writing any code. If you want full control over the design of your push primer, you can build one using a Custom HTML in-app campaign. See Request push notification permission in Create Custom HTML content for In-App Campaigns for more details.

With Xtremepush, you can build push primers using standalone in-app campaigns. In the campaign, you design your push primer message and specify the SDK event that triggers it.

These campaigns can be configured in the following message formats:

• Modal: The push primer is configured on a button within the message.
• Banner: The push primer is set at the message level, and tapping anywhere on the banner triggers the push permission dialog.
• Full Screen: The push primer can be set at the message level, on a button, or both.

For more information on setting up Modal, Banner, and Full Screen Campaigns, see In-App Modal, In-App Banner, and In-App Full screen.

👍

You do not need to configure a decline option in your push primer as users can close the in-app message.

Campaign Setup

To configure a push primer campaign, do the following:

1. Click Create Campaign and then select In-App / Onsite.
2. In the Setup tab, select the In-App channel.
3. In the Content tab, select the Type of in-app message and design the content for your push primer:

   • Modal: The push primer can be added as a button. When a user clicks this button, the push permission dialog is displayed. Configure this button in the Form tab:

     1. In the Action drop-down, select Request Push Permission.
     2. Enter the button label in the Text field.
     3. Leave the Save and Trigger drop-downs set as None.
     4. Select the button checkbox to preview the button. The example below shows an Enable Notifications button added to a modal campaign. When a user clicks it, the push permission dialog is displayed.

     

   • Banner: Tapping anywhere on the banner triggers the push permission dialog. To configure this, in the Portrait tab, select Request Push Permission in the Action drop-down.

     

   • Full Screen: You can configure the push permission action at the message level, on a button, or both:

     • Message Level: Tapping anywhere on the full-screen message triggers the push permission dialog. To configure this, in the Portrait tab, select Request Push Permission in the Action drop-down.

     

     • Button: Tapping on a button in the full screen message triggers the push permission dialog. To configure this:
       1. In the Portrait tab, click Add Button
       2. In the Action drop-down, select Request Push Permission.
          1. Enter the button label in the Text field
          2. Leave the Save and Trigger drop-downs set as None. The following example shows a button configured to request push permission in a full-screen campaign.

     

4. In Trigger tab, select your SDK event that will trigger the push primer message.
5. Before you launch your campaign, see Triggering the Push Primer Event below.

Once your campaign is live, when a user triggers the SDK event, the push primer message appears. Users who have already granted push notification permission will not see the primer.

Triggering the Push Primer Event

Before sending the event that triggers your push primer campaign, check whether users are eligible to receive the notification prompt. You can do this using canRequestNotificationPermission. If this method returns true, you can proceed to send the event and the push primer is displayed.

This ensures that the event is only sent when the push notification permission dialog can be shown to the user.

// Check if the user is eligible to receive the notification prompt.
if (mPushConnector.canRequestNotificationPermission(this)) {
    // Trigger the in-app campaign.
    mPushConnector.hitEvent("inapp-primer", "");
}

// Before showing your in-app push primer, check whether iOS will allow a permission prompt.
// If permission has already been granted/denied, iOS will not show the system prompt again.
[XPush canRequestNotificationPermission:^(BOOL canRequest) {
    if (canRequest) {
        // Trigger your Xtremepush in-app campaign via an event.
        [XPush hitEvent:@"inapp-primer"];
    }
}];

XPush.canRequestNotificationPermission { canRequest in
    if canRequest {
        // Trigger your in-app "push primer" campaign via an event
        XPush.hitEvent("inapp-primer")
    }
}

👍

The event name "inapp-primer" used in the examples can be any string, it just needs to match the trigger event configured in step 4 of the campaign setup above.