Push Notifications

Push notifications are a great way to communicate with people using your app. With Rock Mobile, you can send messages to specific individuals, communication lists, or to everyone that has the app installed, even when they're not signed in.

Authoring Notifications

If you've used the Communication Wizard in Rock to send emails or SMS messages before, you'll be right at home. You can read more about how to use this in the Communicating With Rock manual.

There are two options for the Open Action - Link to Mobile Page and Show Details. The former is self-explanatory, allowing you to reference a mobile app page (don't pick a page from a non-mobile site). You can also pass query strings, which may be needed depending on which page you're linking to. For example, if you want to promote the latest message that was just posted, you can link to the Message Details page and pass a query string of Guid with the value of the content channel item's GUID, assuming you're using this flow to power your messages in-app.

When selecting the Open Action of Show Details, a text editor will appear. Many of the formatting options available here will not be shown in the app, so keep your message as basic as possible. In general, the same Supported Tags in HTML should work here. This will open the message in the app if you've got the Communication View block configured.

You can also add images to your details message. These will not be shown in the notification itself, only in the app when the notification is opened. It's recommended to resize and compress your image to optimize performance and avoid image pop-in when the page is opened.

For a standard 16:9 image, we'd recommend no larger than 960x540 and a few hundred KB.

You'll typically want 100% when adding images so they stretch full-width.

Configuration

During the App Factory process, app notifications are configured. A few changes must be made within your Rock instance to ensure your app users are able to receive push notifications properly.

Service Account JSON

To properly configure the push notification transport, you should download your Service Account JSON from the Triumph Tech Partner Portal. If you can't see your mobile application listed, you should reach out for support from Triumph Tech.

Communications

Rock administrators will need to access the Communications page via 'Admin Tools'. Both the 'Communication Transport' and 'Communication Mediums' pages will need to be accessed in order to establish the connection between Rock and the push notification system that will ultimately be sent through Apple and Google.

Communication Transport

Locate the line item 'Rock Mobile Push'. This property is required in order for the Rock instance to successfully generate an individual's Personal Device Id (See Personal Device Id below for more information).

Communication Mediums

The Communication Transport is only the first of a two-part setup process within the Rock instance. Once the transport is enabled, Rock must understand that you would like to utilize the 'Rock Mobile Push' transport as the Push Notification Medium. Within Communication Mediums, a 'Push Notification' property must be set.

Ensure Push Notifications are 'Active', and the transport container is 'Rock Mobile Push'

With the aforementioned communication changes set, the Rock instance is one last step away from being able to send push notifications successfully.

Setting Up The App

In order for someone to receive a notification from your app, they must have notifications enabled. To do that, the app must request access to send notifications, allowing them to define their preferences. There's a command called EnablePushNotifications that you can use to initiate this request. There is also an application setting called Enable Notifications Automatically under Advanced Settings. When enabled, this will request notification access at launch.

You may want to determine on a page if Push Notifications are enabled and ready for use so that you can prompt the user to enable them. For example, if you have a page that lets the user sign up to receive push notifications about an upcoming event, you might want to make sure notifications are enabled - or at least tell the user they have disabled them. We provide two values in your AppValues model to detect these states.

1. core_PushNotificationHasBeenRequested - This will be a True boolean value if the user has ever been prompted to enable push notifications. Otherwise, it will be False.
2. core_NotificationsAreEnabled - This will be a True boolean value if notifications are determined to be enabled on the device. Otherwise, it will be False.

In the example below, we are manually building an if-else block by making use of the IsVisible properties. The first StackLayout will be shown if the user has never been asked to enable push notifications. The second StackLayout will be shown if the user has been asked but either denied or disabled notifications. The third and final StackLayout will be shown if they have been both asked and have notifications enabled.

Additionally, the first block will let them click a button to enable notifications. The second block has a button they can click to go to Settings and turn notifications back on.

You might wonder why we are doing it this way even though the AppValues are accessible via Lava. The reason to use bindings like this is so the UI is reactive. Suppose they have manually turned off notifications. The second block will show prompting them to go to settings and re-enable them. The user clicks the button, goes to settings and turns notifications back on, and then returns to the application. As soon as the app loads it will update the AppValues which will trigger the Binding to update and hide the second block and show the third block instead. All without having to actually reload the page.

//- If
<VerticalStackLayout IsVisible="{Binding AppValues.core_PushNotificationHasBeenRequested, Converter={Rock:InverseBooleanConverter}}">
    <Label Text="Would you like to enable push notifications?" />
    <Button StyleClass="btn,btn-primary"
        Text="Enable Notification"
        Command="{Binding EnablePushNotifications}" />
</VerticalStackLayout>

//- Elseif
<VerticalStackLayout IsVisible="{Binding AppValues.core_PushNotificationHasBeenRequested}">
    <VerticalStackLayout IsVisible="{Binding AppValues.core_NotificationsAreEnabled, Converter={Rock:InverseBooleanConverter}}">
        <Label Text="Your notifications are disabled, would you like to fix that?" />
        <Button StyleClass="btn,btn-primary"
            Text="Settings"
            Command="{Binding OpenAppSettings}" />
    </VerticalStackLayout>

    //- Else
    <VerticalStackLayout IsVisible="{Binding AppValues.core_NotificationsAreEnabled}">
        <Label Text="You'll be hearing from us." />
    </VerticalStackLayout>
</VerticalStackLayout>

Sending a Push Notification

Now that the Push Notification medium is established, the Rock instance understands where the Push Notification communication is sent. The final step to sending a push notification is to enable the Push Notification communication option within the 'New Communication' block settings.

After selecting a communication list or generating a manual list, a prompt for the communication medium will appear. To send a push notification select 'Push'.

Alternative Sending Methods

Rock allows for more than just the ability to send push notifications via a communication list or manual list. The Mass Push Notification allows the Rock instance to send anyone who has downloaded the app a push notification regardless of if the user is logged in. This is quite powerful and should be used for special circumstances. For example, Mass Push Notifications are useful if the "Campus is closed due to weather". There are many uses for this functionality but bear in mind that when it is used, everyone, no matter their login status will receive a push notification.

There's also a workflow action called Send Push Notification. You can provide the page that individuals will open in the app when they tap the notification. As you might imagine, this unlocks powerful capabilities with alerts or conditional notifications.

Personal Device ID

Each time the Rock Mobile application is downloaded, a Personal Device and ultimately a Personal Device Id (PersonalDeviceId) is generated. The id that is generated within that field is utilized by the communication transport's server key to make a connection to the push notification system for device verification. If the push notification system has the same device ID, a push notification will be sent when generated. Otherwise, the generated push notification will fail to send.

This is one of the first points of emphasis to debug if push notifications are failing to send but all aforementioned steps of the setup process are successfully established. Below is a helpful SQL query that can be run to ensure users and devices are receiving a valid 'PersonalDeviceId'.

SELECT
  p.[NickName],
  p.[Id],
  pd.[Id] AS [DeviceId],
  pd.[PersonAliasId], 
  pd.[Name],
  pd.[DeviceRegistrationId],
  pd.[Guid]
FROM [PersonalDevice] pd
  LEFT JOIN [PersonAlias] pa ON pd.[PersonAliasId] = pa.[Id]
  LEFT JOIN [Person] p ON pa.[PersonId] = p.[Id]