Push Notifications

Purpose

Push notifications are used to update the user about any activity that is organized by the business and applicable to the user. Various notifications are sent to the user for various events. These notifications can be seen under the ‘Inbox’ tab, and they can be in the form of rich message. These notifications allow the user to redeem any particular offer applicable to that user on any purchase.

Push Tokens

Punchh-built apps automatically capture and send the appropriate tokens to Punchh to support push notifications. If you are building a third-party application, we suggest the following:

1. Capture a new push token on a fresh app install.

2a. When a user signs up for the first time, capture the push token and send it to Punchh in the Sign-up / Register API endpoint.

Example: iOS

{
 "client": "CLIENT_GOES_HERE",
 "user":{
 "first_name": "FIRST_NAME_GOES_HERE",
 "last_name": "LAST_NAME_GOES_HERE",
 "email": "test@example.com",
 "password": "PASSWORD_GOES_HERE",
 "password_confirmation":"PASSWORD_GOES_HERE",
 "apn_token": "APN_TOKEN_GOES_HERE"
 }
}

Example: Android

{
 "client": "CLIENT_GOES_HERE",
 "user":{
 "first_name": "FIRST_NAME_GOES_HERE",
 "last_name": "LAST_NAME_GOES_HERE",
 "email": "test@example.com",
 "password": "PASSWORD_GOES_HERE",
 "password_confirmation":"PASSWORD_GOES_HERE",
 "gcm_token": "GCM_TOKEN_GOES_HERE"
 }
}

Note: While the parameter name in Punchh APIs remains as "gcm_token," you should provide an FCM (Firebase Cloud Messaging) token as the value for this parameter in the API call.

2b. If you cannot capture the push token during the Sign-up API call, an alternative is to make an Update User Profile API call immediately after the sign-up is completed. This User Update call should include the application's push token data, similar to how it's done in Option 2a.

Example: iOS

{
  "client": "CLIENT_GOES_HERE",
  "user": {
    "first_name": "FIRST_NAME_GOES_HERE",
    "last_name": "LAST_NAME_GOES_HERE",
    "email": "test@example.com",
    "apn_token": "APN_TOKEN_GOES_HERE"
  }
}

Example: Android

{
  "client": "CLIENT_GOES_HERE",
  "user": {
    "first_name": "FIRST_NAME_GOES_HERE",
    "last_name": "LAST_NAME_GOES_HERE",
    "email": "test@example.com",
    "gcm_token": "GCM_TOKEN_GOES_HERE"
  }
}

Note: While the parameter name in Punchh APIs remains as "gcm_token," you should provide an FCM (Firebase Cloud Messaging) token as the value for this parameter in the API call.

3. If a user logs out of the mobile application, we suggest that you send an Update User Profile API call passing the push token as an empty string to nullify the push token. Doing so prevents a user targeted by a marketing campaign from receiving a push notification while in the logged-out state.

Example: iOS

{
  "client": "CLIENT_GOES_HERE",
  "user": {
    "apn_token": ""
  }
}

Example: Android

{
  "client": "CLIENT_GOES_HERE",
  "user": {
    "gcm_token": ""
  }
}

App Flow and Validations

Step 1: The user signs up and clicks on the ‘Inbox’ icon at the bottom tab.

Step 2: The user will be able to see all notifications for rich message and offers under this tab.

Step 3: Tapping on an offer redirects the user to the offer details screen, which has the offer image, description, and expiry available with a button to redeem the offer.

Step 4: The user can simply read the notifications (News, Signup, Offer Expiry, Welcome Offer) under the list. Tapping on News items does not have any details.

Step 5: To mark notifications as read via push, you can use the Mark Read API and specify the notification IDs you want to mark as read in the API request and the event type as "app_open_via_push".

Validations

1. Inbox screen shows all ‘Notifications’ applicable to a user. All notifications are News. Offers are sent to a user via Campaigns or Support Activity.

2. Badge count always appears on the App icon on the Device screen.

3. For any notification or offer, the Badge updates regardless of the fact that the app is in the foreground, in the background, or not launched.

Check-in Notification

Various cases of check-in notifications are specified below:

Checkin Retry Fail
Checkin Retry Success
Checkin Void
Pending Check-in
POS Scanner Check-in

This notification is sent by Punchh when a check-in happens from the POS (e.g., using a QR code or phone number) or via Online Ordering (initiated by external services such as Olo/NuOrder).

Redemption Notification

Below is the case for Redemption Notification:

Points To Reward/Currency

Survey Notification

This notification is sent from the Beacon Exit campaign or Mass Campaign. Survey is a TypeForm URL where the survey is configured, and it is to be opened in a web view within the mobile app.

Push Notifications

This notification is sent when an incoming webhook from a gift card processor updates the balance of a gift card on Punchh. As soon as the app receives this push notification, the app should update the gift card balance by making a Gift Card Balance API call.

Platform Configurations

Push notifications can be configured in the platform from the Notification Template, where an admin can set notifications for various events:

Loyalty Program > System Messages > General > [choose any template to set notification data].

A Google Cloud Messaging (GCM) Key or Firebase Cloud Messaging (FCM) Key is required to configure push notifications for Android devices. Contact your Punchh representative for information about how to access the Android API key in the Punchh platform.

Similarly, a .p8 certificate file is required for the push notifications configuration for iOS devices. Additional configuration is needed for push notifications to work. Contact your Punchh representative for information about how to access the Apple auth key in the Punchh platform and for assistance in setting up push notifications.

Notifications Payload

Some push notifications receive payload along with the notifications:

Check-in Notification

This notification is sent by Punchh when a check-in happens from the POS (e.g., using a QR code or phone number) or via Online Ordering (initiated by external services such as Olo/NuOrder). The payload received in this push notification has the following keys:

{
"aps": {
"alert": {
"title": "Points Earned",
"subtitle": "You've earned points!",
"body": "You've got 12 points from your last visit at Brooklyn Location!"
},
"sound": "default",
"badge": 10
},
"f": 0,
"i": 23573125,
"n": 96763507,
"p": 12,
"t": "POS_6118542_1487057215",
"u": 6118542
}

'alert' is used to display the notification.
'badge' is used to display on the app icon.
'f' is set to 1 if it is the first check-in, or set to '0' for all subsequent check-ins. If there is a use case of doing something special after the first check-in, this is the key to read from.
'i' is the checkin_id. This is used to identify the check-in in the response received in transaction detail as discussed in the description of 't' below.
'n' contains the notification_id. This is also not used.
'p' has the number of points that were earned using that check-in. These points are used on the congratulations screen. e.g., "Congratulations! You earned 12 points." The value 12 is picked from this key.
't' has the transaction_id. The app takes this transaction ID and makes a call to the Transaction Details API.
Based on the information returned, more information can be displayed on the Congratulations screen, such as displaying the level name if the check-in changed the membership level for that user. This API request is made only if it is required.
'u' has the user_id of the user who made the check-in.

Survey Notification

This notification is sent from the Beacon Exit campaign or Mass Campaign. Survey is a TypeForm URL where the survey is configured, and it is opened in a web view within the mobile app. The payload received in this push notification has the following keys:

{
"aps": {
"alert": {
"title": "How was your visit",
"subtitle": "Share your experience!",
"body": "Please share your experience from your last visit at Brooklyn Location."
},
"sound": "default",
"badge": 10
},
"f": 0,
"n": 96763507,
"p": 1,
"u": 6118542,
"s": 123456
}

's' contains the survey_id. This survey ID is sent as the parameter 'user_survey_id' in the Fetch User Survey API.
These payloads get transferred to the app when the app is running in the foreground, or when a guest taps on the notification when the app is not running or is in the background. When the payload is transferred to the app, the app can implement functionality such as opening a congratulations screen when the payload has, for example, 't', 'i', and 'p' as not null or launching the survey when a guest has tapped on a push notification with payload 's' containing the survey ID. If the Transaction Details API has the survey URL as not null, this survey is launched after the congratulations screen.
There are also cases where 's' is received in check-in push notifications. In such cases, the survey is launched after the congratulations screen. The survey URL in this case can be picked from the Transaction Details API.

Redemption Notification

This notification is sent when a redemption is processed from the POS (after the check is finalized). It is configurable whether this notification will be sent or not. The payload received in this push notification has the following keys:

{
"aps": {
"alert": {
"title": "You've got a discount",
"subtitle": "You've got a discount",
"body": "You've got a discount"
},
"badge": 2
},
"n": 96763507,
"rd": 3,
"u": 6118542
}

'rd' contains the discount that was applied on the check as a result of the redemption.
If there is a requirement to show a special screen when the redemption is processed on the POS, the app should be programmed to read the payload, and if the 'rd' key has a value set, that screen should be displayed.

Gift Card Notification

This notification is sent when an incoming webhook from a gift card processor updates the balance of a gift card on Punchh.

{
"gc":3122
}

'gc' contains the gift card ID.
As soon as the app receives this push notification, the app should update the gift card balance by making a Gift Card Balance API call.

Notifications and Badges Count

Generating x-pch-digest Header for Mobile APIs