Menu
Menu Sheet Overlay
Search
Search Sheet

Configuring Push Messaging

    IMPORTANT: You will need to run all npm scripts mentioned in this guide from the web directory inside your project directory.

    Before you begin #

    You will need to have:

    You will need to:

    Project generation

    When run, the Mobify Project Generator will ask you whether you want to enable a messaging integration. Regardless of your answer, the relevant files will still be generated for push messaging, so you won’t have to worry about your answer if you’re unsure of whether your project actually has push messaging in scope for a future phase. Depending on your answer, the messagingEnabled flag in the web/package.json file will be edited with the appropriate value. If you want to disable push messaging, set that to false and vice versa.

    The messaging configuration file #

    The Mobify Project Generator will configure your PWA for push messaging based on the answers you give during the setup process. You can adjust these settings by editing the messaging configuration file in web/messaging directory inside your project directory. The file is called <project-id>.yaml (where project-id is your project’s identifier).

    Additional steps for iOS apps #

    If you are building an iOS application in addition to your PWA, you must request a certificate file from Apple to authorize Mobify to send push messages to your iOS app for you.

    If you are not building an iOS application in addition to your PWA…

    Requesting a certificate from Apple #

    1. Run npm run messaging:certificate. This will generate a certificate-request file that is signed with a Mobify private key in the web/messaging directory inside your project directory. It will be named <app-id>.csr (where <app-id> is your iOS application’s identifier).
    2. Log into your Apple Developer account at https://developer.apple.com/.
    3. Choose Certificates, IDs and Profiles in the sidebar.
    4. If you haven’t created your App ID, choose App IDs in the left column, and click the + button to add a new App ID.
    5. Once your App ID is set up, choose Production under Certificates in the left column, then click the + button to add a new iOS certificate.
    6. From the Production set of types, choose Apple Push Notification service SSL (Sandbox & Production). Click Continue and choose your App ID.
    7. Continue to the screen that asks you to upload your certificate request (CSR) file. Click Choose File… and upload the certificate request file you generated in earlier.
    8. Download the resulting certificate file. It will be named production.cer.
    9. Rename the certificate file to <app-id>.cer (where <app-id> is your iOS application’s identifier).
    10. Copy the renamed file to the web/messaging directory inside your project directory.

    You can now delete the certificate request file because it is only required to generate the certificate.

    You can safely store the certificate file in a version control system since it is not usable without Mobify’s private key. The private key is held in the Mobify Messaging System and is never downloaded as part of your project.

    Renewing certificates #

    Apple-issued certificates are valid for one year. When your certificate is close to expiration, you can renew it by following the steps above to generate a new certificate-request file, which you can then use to generate a new certificate.

    Uploading your messaging configuration #

    You must upload your messaging configuration file and certificate file (if used for iOS messaging) to Mobify’s push messaging server whenever you start a new project and whenever these files are changed.

    To upload the files, run npm run messaging:upload. The command will report any informational, warning, and error messages from the upload process and from validating the uploaded files. If there are any errors reported, your configuration will not be stored, so you will need to correct the errors and run the upload command again. If there are no errors reported, then push messaging has been successfully configured for your project.

    Sending test messages #

    You can test push messaging by opting-in to push messaging and sending yourself some messages. To do this, you’ll need your client_id string – a 16-character string that uniquely identifies a subscriber to Mobify push messaging. This string is stored as window.Mobify.WebPush.CLIENT_ID once the loader.js file has been loaded and run.

    You can then send a test message using the command npm run messaging:testmessage followed by the client_id value.

    For example, to send a test message to the client with client_id value e70163bff27bf1ff:

    npm run messaging:testmessage e70163bff27bf1ff
    

    You can optionally specify the title, text and icon URL for the test message. To see the full set of options, use:

    npm run messaging:testmessage -- --help
    

    Note that you must put -- before any test message options because of how npm run works. For example, to specify the title:

    npm run messaging:testmessage e70163bff27bf1ff -- --title 'This is a custom title'
    

    Non-progressive Configuration #

    Push messaging is configured for desktop (non-PWA) browsers by editing the web/non-pwa/non-pwa.js file. When a project is generated, and the steps above have been performed to upload the configuration file, desktop push messaging is already configured, to:

    You can use the test message commands above to send test notifications to opted-in PWA and non-progressive browsers.

    Customization #

    The init function of web/non-pwa/non-pwa.js calls initMessaging, passing the messagingConfiguration object. This configuration object contains the parameters that control how non-progressive Messaging presents the opt-in prompt. This prompt is called the ask, and in non-progressive mode it’s done using an iframe that’s displayed at the bottom of a page after a number of site visits and page views. This is how it might appear in Chrome:

    Non-progressive ask

    Customizing the ask text and styles

    In a newly generated project, the HTML for the ask iframe is taken from web/non-pwa/default-ask.html (the styles for this iframe are in web/non-pwa/styles). You can customize these files to replace the default message and styling. You should preserve the existing class names such as js-button-container and the js-allow and js-deny button ids, because SDK code uses them to detect DOM elements, but you can add extra new class names to any elements.

    Customizing the ask behaviour

    In the messagingConfiguration object:

    const messagingConfiguration = {
        defaultAsk: {
            html: defaultAskHtml,
            auto: true,
            showOnPageCount: 3,
            deferOnDismissal: 3
        }
    }
    
    defaultAsk

    The defaultAsk object contains the parameters for the standard ask iframe:

    html string

    This is the HTML for the iframe shown to prompt the user to opt-in to receive push notifications. By default, this is the contents of web/non-pwa/default-ask.html.

    showOnPageCount

    This integer (default value 3) is the number of page views that pass before the ask is shown. A user who have viewed several pages of the site is more engaged, and more likely to opt-in. This counter includes page views across multiple visits to a site.

    deferOnDismissal

    This integer (default value 3) sets the number of separate site visits that a user must make after dismissing the ask without opting-in, before the ask may be shown again. This is set so that a user isn’t re-asked too frequently. A new site visit starts 6 hours after the last page view on a previous visit.

    auto boolean

    This should be set to true to have the SDK code handle all the work of displaying and hiding the ask iframe, and handling subscription to push notifications if the user responds to the ask.

    Setting auto to false allows you to customize when the ask is presented. To do this, you would use the object returned from initMessaging. It contains two values:

    The AskFrame object has the following methods (none take any parameters):

    Turning on push messaging

    To turn on push messaging after configuring all the required components and setting it up within your project, you’ll also need to reach out to your Mobify Customer Success Manager to enable the feature and to also set up Connection Center for your project.