---
title: "Configure Push Primers"
slug: "configure-push-primer"
updated: 2026-06-08T10:02:24Z
published: 2026-06-08T10:02:24Z
canonical: "docs.xtremepush.com/configure-push-primer"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Push Primers

Configure push primers using standalone in-app campaigns.

## 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.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/f7079b49f4cdaaada7bc4e10c4dd4cafa4831af596225ab10176144ee4bca83c-image_7.png)

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.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/69529d3034b81dda17ce9f5d9b3d1715c459ff27c892063912e9cf76e86af458-Screenshot_2026-04-29_at_12.18.13.png)

> [!TIP]
> 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

> [!NOTE]
> 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](/documentation/docs/in-app-custom-html) 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](/documentation/docs/in-app-modal), [In-App Banner](/documentation/docs/in-app-banner), and [In-App Full screen](/documentation/docs/in-app-full-screen).

> [!TIP]
> 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.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/a95d00a0f906a7fc6bb612b475436636c995365d9a7930238006875eef52a7e7-Screenshot_2026-04-30_at_10.05.23.png)

Example Modal Push Primer
  - **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.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/44feaedfe111924a3a098a0e5faeb5e1e2c507df2c3a7f3e94003d61b055f4b8-Screenshot_2026-04-30_at_10.12.31.png)

Example Banner Push Primer
  - **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.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/7d5826f3a83aebdb1e7aa6d041e59f6efd8253e1a51defd7799d1e7565538fb8-Screenshot_2026-04-30_at_10.26.44.png)

Example Full Screen Push Primer (Message Level)
    - 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**.

![](https://cdn.document360.io/b056e88b-f6c1-4bd2-b5b8-08e9336a17c9/Images/Documentation/1aa7771ee40e7f609ea272a6b3eab4f3d628ee9117d04c7431d91e0f6f813bb3-Screenshot_2026-04-30_at_10.28.06.png)

Example Full Screen Push Primer (Button)
        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](/docs/configure-push-primer#triggering-thepush-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.

**Java**

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

**Objective-C**

```objectivec
// 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"];
    }
}];
```

**Swift**

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

> [!TIP]
> 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.