UnifiedPush
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
Edit page

Embedded FCM Distributor

If you want your app to fallback to FCM on Android if:

  1. Your user doesn’t have any UnifiedPush Distributors and
  2. They have Google Services enabled

This is for you. You can embed an FCM Distributor, and if the user doesn’t have another distributor, this one will be used. These libraries basically act like UnifiedPush Distributors, but are internal to the app and pass notifications through FCM.

There are 2 libraries doing it: one using the Google Firebase library and another (beta) entirely FOSS* that doesn’t.

About

  1. The Android Embedded FCM Distributor is the original embedded distributor. It uses the official Google library for FCM support. However, it is proprietary thus cannot be included on app-stores like F-Droid.
  2. The Android FOSS Embedded FCM Distributor is a new library. It reimplements the same API that the Google library uses. Since it’s open source, it can be used on FOSS app stores like F-Droid.

Usage

You will need to add some code on your android project and host a FCM Rewrite proxy. For Flutter projects, do the following in the android directory.

Android

  • Add classpath 'com.google.gms:google-services:4.3.8' to your project level build.gradle.
  • Add id 'com.google.gms.google-services' and the following implementation to your app level build.gradle.
    implementation('com.github.UnifiedPush:android-embedded_fcm_distributor:2.0.0') {
        exclude group: 'com.google.firebase', module: 'firebase-core'
        exclude group: 'com.google.firebase', module: 'firebase-analytics'
        exclude group: 'com.google.firebase', module: 'firebase-measurement-connector'
    }
  • Apply google-services plugin for your fcm flavor in your app level build.gradle. (You may need to edit the pattern)
def getCurrentFlavor() {
    Gradle gradle = getGradle()
    String  tskReqStr = gradle.getStartParameter().getTaskRequests().toString()
    String flavor

    Pattern pattern

    if( tskReqStr.contains( "assemble" ) )
        pattern = Pattern.compile("assemble(\\w+)")
    else
        pattern = Pattern.compile("generate(\\w+)")

    Matcher matcher = pattern.matcher( tskReqStr )

    if( matcher.find() ) {
        flavor = matcher.group(1).toLowerCase()
    }
    else
    {
        println "NO MATCH FOUND"
        return ""
    }

    pattern = Pattern.compile("^fcm.*");
    matcher = pattern.matcher(flavor);

    if( matcher.matches() ) {
        return "fcm"
    } else {
        return "main"
    }
}

println("Flavor: ${getCurrentFlavor()}")
if ( getCurrentFlavor() == "fcm" ){
    apply plugin: 'com.google.gms.google-services'
}
  • Add the google-services.json file from firebase to your app directory.
  • Add the receiver to your code:
class EmbeddedDistributor: EmbeddedDistributorReceiver() {
    override fun getEndpoint(context: Context, fcmToken: String, instance: String): String {
        // This returns the endpoint of your FCM Rewrite-Proxy
        return "https://<your.domain.tld>/FCM?v2&instance=$instance&token=$token"
    }
}
  • Declare it on your Manifest:
        <receiver android:enabled="true"  android:name=".EmbeddedDistributor" android:exported="false">
            <intent-filter>
                <action android:name="org.unifiedpush.android.distributor.feature.BYTES_MESSAGE"/>
                <action android:name="org.unifiedpush.android.distributor.REGISTER"/>
                <action android:name="org.unifiedpush.android.distributor.UNREGISTER"/>
            </intent-filter>
        </receiver>
  • Add the following implementation to your app level build.gradle.
    implementation('com.github.UnifiedPush:android-foss_embedded_fcm_distributor:1.0.0-beta1')
  • Add the receiver to your code:
package YOUR.PACKAGE.ID

import android.content.Context
import org.unifiedpush.android.foss_embedded_fcm_distributor.EmbeddedDistributorReceiver

class EmbeddedDistributor: EmbeddedDistributorReceiver() {

    override val googleProjectNumber = "123456789012" // This value comes from the google-services.json

    override fun getEndpoint(context: Context, token: String, instance: String): String {
        // This returns the endpoint of your FCM Rewrite-Proxy
        return "https://<your.domain.tld>/FCM?v2&instance=$instance&token=$token"
    }
}
  • Declare it on your Manifest:
        <receiver android:enabled="true"  android:name=".EmbeddedDistributor" android:exported="false">
            <intent-filter>
                <action android:name="org.unifiedpush.android.distributor.feature.BYTES_MESSAGE"/>
                <action android:name="org.unifiedpush.android.distributor.REGISTER"/>
                <action android:name="org.unifiedpush.android.distributor.UNREGISTER"/>
            </intent-filter>
        </receiver>

FCM Rewrite Proxy

As a developer, if you’re using the FCM embedded distributor, you will need a rewrite proxy for FCM-fallback for users who don’t have a UnifiedPush Distributor. It is close to the usually needed gateway to FCM or trusted server

We recommend using the following as the gateway.

UnifiedPush Common-Proxies is a program can be installed to run as a rewrite proxy for FCM. If you don’t have a server to host this on, ask in the UnifiedPush chat, we can help out.

Traffic from /FCM on any reverse proxy (for TLS) can be proxied to it. The following is an example for Nginx.

location  /FCM {
        proxy_pass            http://127.0.0.1:5000;
}

Firebase setup

Create a new project

If you already have a Firebase project, skip this section and just open your project settings.

  • Click on ‘plus’ Add project See adjacent text
  • Set a name for your project, continue and configure the rest of the project. See adjacent text
  • Click on the gear icon and open project settings See adjacent text

Configure Cloud Messaging

  1. Click on the Cloud Messaging tab See adjacent text
  2. If you already see a server key under Cloud Messaging API (Legacy), then go to step 6.
  3. Else, open the menu of this section, and click on Manage API in Google Cloud Console See adjacent text
  4. In the Cloud Console page that opened, click on Enable See adjacent text
  5. Go back to the Firebase Cloud Messaging page, and reload it. You should now see a server key. See adjacent text
  6. This server key will be used to configure Common Proxies.

Configure Android app

If you have already added an Android application to your project, skip this section.

  1. Click on the Android logo under Your apps See adjacent text
  2. Enter your Android application’s package name. See adjacent text
  3. Press ‘Next’, ‘Next’, ‘Continue’ and go back to your settings console.

Setting up your app on Android (FOSS FCM lib)

Setting up your app on Android (Google FCM lib)

  • Under the menu Your apps, download google-services.json.
  • Place it at app/google-services.json in your Android project
  • If you’re using Flutter, place it at android/app/google-services.json