Mobile push (Android)

Before you start

• A Firebase project with your Android app added to it (the app’s package name, for example com.example.shop).
• The Tranthor Android SDK in your app, with its push module (below).
• An Admin or Workspace manager role in Tranthor, to add the key.

1. Create a Firebase service-account key

1. Open the Firebase console and select the project your app uses.
2. Go to Project settings, then Service accounts.
3. Select Generate new private key. Firebase downloads a JSON file. If Firebase says key creation is not allowed, see Troubleshooting.

2. Add the key in Tranthor

1. In Tranthor, go to Settings, Mobile, Push.
2. On the Android (FCM) card, select Add key.
3. Enter your app’s application id (its package name) and choose the JSON file, or paste its contents.
4. Select Save.

3. Install the SDK and bind push

val push = TranthorPush.bind(
    context,
    PushConfiguration(applicationId = BuildConfig.APPLICATION_ID),
    sdk,
)

class MyMessagingService : TranthorMessagingService() {
    override suspend fun tranthorPush(): TranthorPush? =
        (application as MyApp).push.await()

    override fun notificationStyle() = TranthorNotificationStyle(
        smallIcon = R.drawable.ic_notification,
        defaultChannelId = "tranthor",
        defaultChannelName = "Updates",
        launchIntent = Intent(this, MainActivity::class.java),
        dismissReceiver = MyDismissReceiver::class.java,
        images = RichImageConfiguration(setOf("images.example.com")),
    )

    override fun onOtherMessage(message: RemoteMessage) = otherSdk.handle(message)
}

Events the SDK sends

What Tranthor sends to the phone

{
  "message": {
    "token": "<fcm-token>",
    "data": {
      "tranthor": "{\"version\":1,\"deliveryId\":\"8c0f2a...\",\"imageUrl\":\"https://images.example.com/a.png\"}",
      "title": "Your order shipped",
      "body": "It arrives Friday.",
      "channelId": "orders",
      "url": "shop://orders/42",
      "orderId": "42"
    },
    "android": { "priority": "HIGH", "ttl": "2419200s" }
  }
}

• tranthor is a JSON string. It holds version (always 1), the deliveryId the SDK reports back, the imageUrl when the template has one, and "test": true for a test push.
• title, body, channelId (the template’s Channel id, under Advanced) and url (the template’s When tapped, open link) are left out when empty.
• The template’s data entries are added as their own keys. A data key named tranthor, title, body, channelId, url, from or message_type, or starting with google. or gcm., is not sent.
• Title, body, image URL, the When tapped, open link and data values can use Liquid, like other templates.
• FCM limits a message’s data to 4096 bytes. A longer message is not sent, and the send fails with a reason.
• FCM keeps an undelivered message for up to 28 days.

Which phones receive a push

• Removed at once: when Google says the token is no longer registered, when the app sends Installation Removed, or when the phone has not registered for 90 days. The SDK registers on every app start, so a phone in use never reaches 90 days.
• Paused after two rejections: when Google rejects a phone’s token twice in a row. A paused phone comes back when the app gets a new token from Firebase.
• Notification permission: a phone the SDK reports as "denied" is skipped. "unknown" still receives push.

Results

• Sent: Google accepted the message for at least one of the customer’s phones.
• Delivered: the app on the phone reported Push Received. This is app-reported: a phone that was off, or an app that did not run its messaging service, reports nothing, so Delivered can be lower than what reached phones.
• Opened: the customer tapped the notification (Push Opened).
• Failed: no phone accepted the message. The Stats tab and a broadcast’s results list failures by reason, in words.
• Not sent: a customer with no phone that can get push from the app is skipped, shown as No active Installation under Push not sent. A skip is neither sent nor failed.

Troubleshooting

Firebase says “Key creation is not allowed on this service account”

1. Make sure you have the Organization Policy Administrator role. If you do not, ask your Google Cloud admin.
2. In the Google Cloud console, go to IAM & Admin, then Organization Policies.
3. In the project picker at the top, select your Firebase project. Do not select the organization.
4. Open Disable service account key creation. There are two entries with this name, a legacy one and a managed one. Open the one that shows Active.
5. Select Manage policy, then Override parent’s policy.
6. Add a rule and set Enforcement to Off. Then select Set policy.
7. Wait up to 15 minutes for the change to take effect.
8. In Firebase, select Generate new private key again.

Current limits

• Android only. iOS (APNs) is not available yet. The editor already lets you prepare iOS: under Settings › Message, Different for each gives the iOS version its own title, subtitle, body and image, and Advanced holds the iOS Sound and Time sensitive options. These are saved with the template and shown in the iOS preview, but nothing is sent to iPhones, and Android phones get the same push as before.
• Turned on per workspace. Ask us to turn it on for yours.
• The Android SDK artifacts are not on Maven yet.
• Push is sent by people in the dashboard. In the push template editor, the AI chat can write and change the template’s draft. It writes the shared (Android) message only, and does not see or edit the iOS version. It cannot publish the template, start a journey or send push.
• The Supervisor and connected assistants such as Claude and ChatGPT can read push templates, journeys and results, but cannot create, start or send push yet.
• Reachable audience and Blast radius counts do not include push yet.