Push notifications
Cheggout needs a way to reach your customer when your app is closed — a reward is waiting, a scratch card is about to expire, a campaign has landed.
There are two ways to deliver that, and they differ in who owns the sending infrastructure.
This is a platform decision, not an SDK setting. The two options need different work from different teams — one needs a backend endpoint from you, the other needs Firebase credentials from your mobile team. Picking late means rework.
Settle it during onboarding, record the choice, and only then start building.
The two options at a glance
| Option 1 — API based | Option 2 — Certificate based | |
|---|---|---|
| Who sends the notification | You do, from your own Firebase | Cheggout does, using your credentials |
| What you build | A send endpoint Cheggout calls | Nothing — you pass an identifier at SDK launch |
| What you hand over | Nothing sensitive | FCM API credentials |
| Who holds device tokens | You. They never leave your systems. | Cheggout can address your users directly |
| Who maps user to device | You, from virtualid | You, by sending the FCM ID at launch |
| Visibility over what is sent | Full — every send passes through you | Limited |
| Effort on your backend | Higher | Minimal |
| Effort on your mobile app | Same in both — you handle the tap | Same in both |
Choosing between them. If you are a bank or hold a licence, Option 1 is almost always the answer: no third party gains the ability to message your customers, and every notification is auditable on your side. Choose Option 2 when speed matters more than control, or when you have no existing push service to extend.
Both options end identically — the notification carries source: "CHGT" and a deeplinkInfo, and
your app uses those to authenticate the user and open the Cheggout SDK on the right screen.
Common to both options
Whichever option you choose, the notification that reaches the device has the same shape:
{
"message": {
"notification": {
"title": "Your Rewards",
"body": "You earned 50 reward points."
},
"data": {
"source": "CHGT",
"deeplinkInfo": "<click>https://rewardscreen.cheggout.com</click>"
}
}
}
| Field | Purpose |
|---|---|
notification.title / notification.body | What the user sees on the lock screen |
data.source | CHGT — how your app recognises this as a Cheggout notification |
data.deeplinkInfo | Where inside Cheggout to open, passed to the SDK as DeeplinkInfo |
source: "CHGT" is what makes the tap workYour app receives notifications from many sources. Branch on data.source == "CHGT" to route
Cheggout notifications into the Cheggout handling path. Without it you cannot tell a Cheggout
notification from your own, and the deep link will be ignored.
What happens when the user taps — identical in both options
The notification is not proof of identity — anyone holding the device can tap it. Run your normal authentication or session check first, then mint the session and launch the SDK. Never treat a notification tap as an authenticated session.
Option 1 — API based
You keep everything. Cheggout tells you what to send and to whom; your infrastructure does the sending.
Step 1 — Build and share the endpoint
1. Expose an endpoint Cheggout can call.
POST https://{api.yourdomain.com}/v2/{sendpushnotification}
You choose the host and path; share the final URL with Cheggout during onboarding.
{
"virtualid": "7934759843759",
"title": "Reward",
"message": "You won a reward",
"deeplinkInfo": "<click>https://rewardscreen.cheggout.com</click>",
"OfferInfo": {
"Mcccode": "32",
"Category": "Shopping"
}
}
| Field | Type | What you do with it |
|---|---|---|
virtualid | string | The user to notify. Resolve this to a device token. |
title | string | Notification title — pass straight through |
message | string | Notification body — pass straight through |
deeplinkInfo | string | Must survive into the payload as data.deeplinkInfo |
OfferInfo | object | Offer context — Mcccode, Category. Use it for your own segmentation or logging. |
2. Resolve virtualid to the user's FCM token.
This is the mapping only you hold. It is the whole point of this option — Cheggout never learns which device belongs to which customer.
3. Send it through your Firebase, tagging it as Cheggout-originated.
When your wallet backend sends the notification, it must add the identifier that lets your app
recognise it later. Set data.source to CHGT and carry deeplinkInfo through unchanged.
- Node.js
- Java
// Your endpoint: Cheggout calls this.
app.post('/v2/sendpushnotification', async (req, res) => {
const {virtualid, title, message, deeplinkInfo, OfferInfo} = req.body;
// 2. Only you can do this mapping.
const fcmToken = await lookupFcmToken(virtualid);
if (!fcmToken) return res.status(404).json({status: 'USER_NOT_FOUND'});
// 3. Tag it so the app can recognise it on tap.
await firebase.messaging().send({
token: fcmToken,
notification: {title, body: message},
data: {
source: 'CHGT', // the identifier — without this the tap does nothing
deeplinkInfo, // pass through unchanged
},
});
res.json({status: 'OK'});
});
@PostMapping("/v2/sendpushnotification")
public ResponseEntity<?> sendPush(@RequestBody CheggoutPushRequest req) {
// 2. Only you can do this mapping.
String fcmToken = tokenStore.lookup(req.getVirtualid());
if (fcmToken == null) {
return ResponseEntity.status(404).body(Map.of("status", "USER_NOT_FOUND"));
}
// 3. Tag it so the app can recognise it on tap.
Message msg = Message.builder()
.setToken(fcmToken)
.setNotification(Notification.builder()
.setTitle(req.getTitle())
.setBody(req.getMessage())
.build())
.putData("source", "CHGT") // the identifier
.putData("deeplinkInfo", req.getDeeplinkInfo()) // pass through unchanged
.build();
FirebaseMessaging.getInstance().send(msg);
return ResponseEntity.ok(Map.of("status", "OK"));
}
deeplinkInfo is the classic failureIf your service forwards the title and body but loses deeplinkInfo, everything still looks
correct — the notification arrives and reads properly — but the tap opens the Cheggout home screen
instead of the reward. Assert the field is present before you send, and test the tap end to end.
Step 2 — Handle the tap in your app
The notification arrives. Your app checks source, authenticates, and launches the SDK with the
deep link. See handling the tap below — the code is the same for
both options.
Your checklist for Option 1
- Endpoint built, deployed, and its URL shared with Cheggout
- Authentication for that endpoint agreed with Cheggout TBD
-
virtualidto FCM token mapping in place, and kept current as tokens rotate -
data.sourceset toCHGTon every Cheggout-originated send -
deeplinkInfocarried through unchanged and asserted before sending - Tap-through tested end to end on a real device
Option 2 — Certificate based
Cheggout sends directly to your users' devices using credentials you provide.
Step 1 — Share credentials and identifiers
1. Share your FCM API credentials with Cheggout.
This is the certificate or service-account credential for your Firebase project. It lets Cheggout send to your users on your behalf.
These credentials let the holder send notifications to every user of your app, not only Cheggout-related ones. Before handing them over:
- Confirm the handover channel is secure — never email or paste them into a ticket.
- Agree who at Cheggout can access them, and how they are stored.
- Agree a rotation process, and rotate immediately if anyone leaves either team.
- Prefer a dedicated service account scoped to messaging over a broadly-privileged credential.
If your security policy prohibits sharing messaging credentials with a third party — as most banks' policies do — use Option 1 instead.
TBD The secure handover process and the credential format Cheggout expects are not published. Agree both with Cheggout before you generate anything.
2. Pass the user's FCM ID when you launch the SDK.
This tells Cheggout which device belongs to the user it is about to reward. It travels in the launch
payload as pushnotificationID.
- iOS
- Android
let payload: [String: Any] = [
"Component": "CHEGGOUT",
"IsEmployee": "0",
"Language": "EN",
"DeeplinkInfo": "",
"pushnotificationID": fcmToken, // the user's Firebase identifier
]
cheggoutApp = CheggoutApp(
userID: virtualId,
sessionInfo: sessionId,
accessInfo: nil,
payload: payload,
exitHandler: { _ in /* cleanup */ }
)
// The documented Android payload string is Component / IsEmployee / Language /
// DeeplinkInfo / customerId. Confirm with Cheggout how the FCM ID is carried here.
val payload =
"{'Component':'CHEGGOUT','IsEmployee':'0','Language':'EN','DeeplinkInfo':'','customerId':''}"
CheggoutApplication.launchCheggout(
this, virtualId, sessionId, payload, activityContext, "YOURCHANNEL"
)
TBD pushnotificationID is documented as an iOS payload key. The documented
Android payload string does not include it. Confirm with Cheggout how the FCM ID should be passed on
Android before you build against this option.
3. Get the exact notification body from Cheggout.
Cheggout composes and sends the notification, so agree the exact payload it will produce — including
that data.source is CHGT and that deeplinkInfo is present — and verify it against a real
device during UAT.
Step 2 — Handle the tap in your app
Identical to Option 1: check source, authenticate, launch the SDK with the deep link.
Your checklist for Option 2
- Security sign-off obtained for sharing FCM credentials with a third party
- Dedicated, messaging-scoped service account created rather than a broad credential
- Credentials handed over through an agreed secure channel TBD
- Rotation process agreed and documented
- FCM ID passed at SDK launch — confirm the Android mechanism TBD
- Exact notification payload confirmed with Cheggout and verified on a device
- Tap-through tested end to end on a real device
Handling the tap in your app
This part is the same whichever option you chose. Recognise the notification, authenticate, then launch the SDK with the deep link.
- Android
- iOS
launchCheggout needs an Activity context, so a FirebaseMessagingService cannot launch the SDK
itself. Carry the deep link into an Activity and launch from there.
// 1. In your FirebaseMessagingService — recognise it and hand off to an Activity.
class PushService : FirebaseMessagingService() {
override fun onMessageReceived(remoteMessage: RemoteMessage) {
// Only Cheggout notifications take this path.
if (remoteMessage.data["source"] != "CHGT") {
handleYourOwnNotification(remoteMessage)
return
}
val deepLink = remoteMessage.data["deeplinkInfo"] ?: ""
val intent = Intent(this, ShopActivity::class.java)
.putExtra("cheggoutDeepLink", deepLink)
.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
// Attach this intent to the notification's PendingIntent so the tap opens ShopActivity.
showNotification(remoteMessage, intent)
}
}
// 2. In the Activity the notification opens — authenticate, then launch.
class ShopActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
val deepLink = intent.getStringExtra("cheggoutDeepLink") ?: ""
// Authenticate first — a notification tap is not an authenticated session.
requireAuthenticatedUser { virtualId ->
// Mint a fresh session from your backend, as on any other launch.
fetchSession(virtualId) { sessionId ->
val payload = "{'Component':'CHEGGOUT','IsEmployee':'0'," +
"'Language':'EN','DeeplinkInfo':'$deepLink'}"
CheggoutApplication.launchCheggout(
this, virtualId, sessionId, payload, this, "YOURCHANNEL"
)
}
}
}
}
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completion: @escaping () -> Void) {
let info = response.notification.request.content.userInfo
// Only Cheggout notifications take this path.
guard (info["source"] as? String) == "CHGT" else {
handleYourOwnNotification(info)
completion()
return
}
let deepLink = info["deeplinkInfo"] as? String ?? ""
// Authenticate first — a notification tap is not an authenticated session.
requireAuthenticatedUser { virtualId in
fetchSession(for: virtualId) { sessionId in
let payload: [String: Any] = [
"Component": "CHEGGOUT",
"IsEmployee": "0",
"Language": "EN",
"DeeplinkInfo": deepLink,
]
self.cheggoutApp = CheggoutApp(
userID: virtualId,
sessionInfo: sessionId,
accessInfo: nil,
payload: payload,
exitHandler: { _ in /* cleanup */ }
)
completion()
}
}
}
What to settle with Cheggout
TBD Several details are not fixed in the published integration document. Raise these in your onboarding call and record the answers:
| Question | Applies to |
|---|---|
| How is your push endpoint authenticated? | Option 1 |
| Retry and failure behaviour if your endpoint is unavailable | Option 1 |
| Expected response body and status codes from your endpoint | Option 1 |
| Secure channel and format for the credential handover | Option 2 |
| Credential rotation process | Option 2 |
| How the FCM ID is passed on Android | Option 2 |
| Exact notification payload Cheggout produces | Option 2 |
| Which events trigger a push, and any frequency capping | Both |
Security
FCM tokens identify a specific user's device. Keep them out of exported logs, support tickets and anything shared outside your team. Never paste a real token into documentation — including this page's examples, which are deliberately synthetic.
- Authenticate on tap. A notification tap tells you the device was held, not who held it.
- Never trust
deeplinkInfoblindly. Treat it as a destination hint you pass to the SDK, not as a URL to open in an arbitrary browser. - Handle token rotation. FCM tokens change. Under Option 1 keep your mapping current; under Option 2 pass the current identifier at every launch.
Next
- Onboarding — where this decision gets recorded.
- Android callbacks · iOS callbacks
- Scratch cards — the module that most often triggers a push.