Skip to content

Mobile app configuration

Mobile apps let you send push notifications to your customers’ phones and tablets through ECDP, using Firebase Cloud Messaging (FCM). There’s no SDK to install – your app talks to ECDP directly through the API, using the same Firebase project you already use to send notifications from your own backend.

This article covers connecting your app to ECDP: setting up Firebase, adding the app in ECDP, registering customer devices, and finding device data on customer profiles. To build and send the actual notifications, see Mobile push notifications.

Requirements

Make sure you have the following ready:

  • A Google Cloud project with Firebase and Cloud Messaging enabled for your Android and/or iOS app.
  • A Firebase service account with permission to send messages, and its JSON key file.
  • Access to your app’s codebase, so your developer can add the API calls needed to register devices with ECDP and report back notification views and clicks.

Set up Firebase for your app

Before you can add a mobile app in ECDP, create a service account in Google Cloud that ECDP can use to send messages through your Firebase project.

  1. In Google Cloud, select the project used by your mobile app.
  2. Enable the Firebase Cloud Messaging API.
  3. Create a service account with permission to send messages – use the Firebase Cloud Messaging API Admin role, or a custom role with the  cloudmessaging.messages.create permission.
  4. Generate a JSON key for that service account and download the file. You’ll upload this file in ECDP in the next step.

Add a mobile app in ECDP

Once you have your Firebase service account ready, create the matching mobile app entry in ECDP.

  1. Go to Settings > Mobile Apps.
  2. Click Configure mobile app.
  3. Enter a name for the app (required, up to 100 characters) and, optionally, a description.
  4. Upload the Firebase JSON key file you generated:
    • If the file is valid, ECDP reads the client_email, private_key, and project_id from it and fills these fields in automatically (read-only).
    • If the file is missing required data, ECDP shows an error and marks the missing fields.
    • If you remove the uploaded file, the auto-filled fields are cleared.
  5. Click Save.

The Firebase file is optional at this stage. You can save the app without it – it’s still created with Active status – and upload it later once you have it. Until valid Firebase configuration is in place, though, ECDP can’t deliver push notifications for this app.

Once saved, ECDP assigns the app a unique ID, shown on the app list in Settings > Mobile Apps. Your developer needs this ID, together with your account’s API endpoint and API key (find both in Settings > API), to connect the app through the API.

What happens automatically when you add a mobile app#

  • ECDP creates a dedicated mobile push channel consent for this app, the same way it does for web push.
  • This consent is active right away.

Connect your app to ECDP

With the mobile app created in ECDP, your developer connects your app’s codebase so it can register devices and report notification activity. On Android, this still requires adding the standard google-services.json file to the app, same as any Firebase integration.

  1. Your app requests an FCM token from Firebase, as usual.
  2. Your app sends the device and token to ECDP: POST /customermobiledevices.
    • Required:
      • the mobile app ID,
      • a device ID, which is a stable identifier that will not change upon app updates, such as installation ID.
      • the FCM token.
    • Optional device details: OS, OS version, device brand, device model, app version, language.
    • Optional customer identifiers: email, phone, or CRM ID. It’s recommended to pass a single, primary identifier, such as email.
  3. To remove a device’s registration – for example after a customer revokes notification permissions – send DELETE /customermobiledevices with the same identifiers.

Registering the same device again, for example after a token refresh just updates the existing record; it doesn’t create a duplicate. If no customer identifier is sent, ECDP links the device to an anonymous customer until it’s identified later.

For full request and response details, see the API reference at Swagger –  CustomerMobileDevices.

How ECDP identifies customers across devices

A device can only be actively linked to one customer at a time. When a device registration includes a customer identifier that doesn’t match what’s already on file, ECDP works out what changed:

  • If the device currently belongs to an anonymous customer and the new identifier matches an existing, known customer, ECDP merges the two: the device (and its history) moves to the known customer, and the anonymous customer is deactivated.
  • If the device currently belongs to a known customer, but the request comes in with a different identifier, ECDP treats it as a new person using the same device: it moves the device to that other customer (creating them if needed), while the original customer keeps their history.

Registering and removing devices through the API handles consent automatically , without any manual steps on your end.

  • Each mobile app has one dedicated consent, shared by all of that app’s devices for a given customer.
  • The consent is granted as long as the customer has at least one active device on that app.
  • Removing a device through the API revokes the consent if it was the customer’s last active device on that app.
  • ECDP also deactivates a device and revokes its consent automatically when Firebase reports the token as no longer valid:
    • an invalid token – shown in delivery statistics as Bounced.
    • an unregistered token – shown in delivery statistics as Unsubscribed.

Track notification delivery and engagement

Every notification ECDP sends is tagged with a messageGuid, a unique identifier for that single notification, included in the payload your app receives from Firebase. Your app reads this value and sends it back to ECDP so each view or click can be matched to the exact notification it came from.

  • Send is recorded automatically by ECDP once the message is handed off to Firebase, no action is needed from your app for this one.
  • View – your app should report this once the operating system actually displays the notification: POST /events/mobile/push/views.
  • Click – your app should report this only when the customer taps the notification: POST /events/mobile/push/clicks.

Both endpoints need only the mobile app ID and the messageGuid from the notification payload. You don’t need to send the device or customer, since ECDP already knows who received it. Report each event once per notification.

Do you send a lot of events? Use POST /events/mobile/batch to submit up to 1,000 view/click events in a single request, instead of calling individual endpoints one by one.

A push notification can carry a deep link that opens a specific screen in your app when the customer taps it. You set the deep link when creating the notification content.

ECDP passes the deep link through as plain data in the notification payload, using the deep_link field. It doesn’t validate the link’s format or open it, that’s entirely up to your app.

  • Make sure your app can correctly interpret and open the deep links you plan to use.
  • Add a safe fallback, such as opening the home screen, for cases where the deep link isn’t recognized.

View a customer’s mobile devices

The Mobile devices section in Customer 360 lists every device linked to the customer, on which you app is installed.

  • Each device appears as a card showing: platform icon, device ID, status (Active or Inactive), the app it belongs to, and the device’s brand and model.
  • The token is truncated on the card – hover to see the full value or use the copy button to copy it.
  • Click a card to expand more details: OS, OS version, app language, and app version.
  • Cards are sorted newest first, two per row. Missing values are shown as “–”.
  • If the customer has no registered devices, the section shows an empty state.

Find customers by mobile device

By default, the Customers grid doesn’t show customers who only have a mobile device and no email, phone, or CRM ID. Once at least one mobile app is configured, a new checkbox appears above the grid: Include mobile device-only customers. It’s unchecked by default, and your choice is remembered, the same way it works for the web push–only customers checkbox.

Manage your mobile app

In Settings > Mobile Apps, select Deactivate on an app to stop it from being used for notifications. A modal explains that once deactivated, you won’t be able to collect consents, track customer behavior or send notifications to your customers through this app.

You can turn a deactivated app back on at any time from the same list, using the Activate action. Deleting a mobile app isn’t possible yet.

FAQ

Can I create a mobile app without a Firebase configuration file?

Yes. The Firebase JSON file is optional when you first create a mobile app – you can save it and add the file later. The app is saved with Active status either way, but ECDP can’t send push notifications for it until valid Firebase configuration is in place.

What happens if I remove the uploaded Firebase file?

If you remove the file while setting up or editing your mobile app, ECDP clears the client_email, private_key, and project_id fields. You can then upload a different file or save the app without Firebase configuration and add it later.

To learn how to create and send mobile push notifications once your app is connected, see Mobile push notifications.

Privacy policy