Legacy Push System

First, v2 is simply Push but more convenient to implement, maintain, and build on top of. We’ve added several features that make push easier and more powerful:

• Easier configuration

• v1 has a template-based customization system and users need to learn the details of this template system.

• v2 has a common message payload where SDKs automatically enrich messages and channels in the runtime and call the callback with these data where it’s a familiar way of building by programming and any customization is possible.

• Multi bundle support for push providers

• Multi-tenancy and continuous delivery are covered in a single Stream app.

• v1 has a limit of 100 members in a channel. If the member count goes higher than this value, newer members won’t receive push notifications.

• v2 doesn’t have this limitation and it will continue working.

Templates in v2

In v2, template functionality is partially dropped to simplify configurations:

1. Standard template, there is nothing to configure

2. By default, data payload size is limited to 4KB. Data is enriched automatically

3. Offline storage is synced under the hood for more performant experience

4. Templates have a steep learning curve and are hard to use and they have their own quirks such as a lack of advanced programming constructs

SDKs receive a standard payload and enrich it by calling API and syncing their storage then they pass data to the user to be used in their familiar environment.

It works well for native platforms but has some deficiencies for non-native SDKs such as React Native and Flutter. In this case, a limited version of templating is supported because the app isn’t woken up to process notifications if it has been killed by OS or user.

Default Firebase APN template

Following is the default template if you leave apn_template or firebase_apn_template empty. To see definition of available fields that can be included in aps object please see Apple documentation.

{
	"aps": {
		"alert": {
			"title": "New message from {{ sender.name }}",
			"body": "{{ truncate message.text 150 }}"
		},
		"mutable-content": 1,
		"category": "stream.chat"
	},
	"stream": {
   "sender": "stream.chat",
   "type": "message.new",
   "version": "v2",
   "id": "{{ message.id }}",
   "cid": "{{ channel.cid }}"
	}
}

Updating Firebase APN template

// for multi-bundle support
const pushProviderConfig = {
  name: "my-name",
  type: "firebase",
  firebase_credentials: "your service worker config",
  firebase_apn_template: "your-template",
};

client.upsertPushProvider(pushProviderConfig);

// for non-multi-bundle support
const firebase_config = {
  credentials_json: "your service worker config",
  apn_template: "your template",
};

client.updateAppSettings({ firebase_config });

Default Firebase Notification template

By default, there is only a data message and no notification in the payload.

If a template is set, then the template will be processed and put into the notification key in the payload. To see available fields and their description please follow FCM documentation.

Following is a sample template for an example:

{
  "title": "{{ sender.name }} @ {{ channel.name }}",
  "body": "{{ truncate message.text 150 }}",
  "click_action": "OPEN_ACTIVITY_1",
  "sound": "default"
}

Updating Firebase Notification template

// for multi-bundle support
const pushProviderConfig = {
  name: "my-name",
  type: "firebase",
  firebase_credentials: "your service worker config",
  firebase_notification_template: "your-template",
};

client.upsertPushProvider(pushProviderConfig);

// for non-multi-bundle support
const firebase_config = {
  credentials_json: "your service worker config",
  notification_template: "your template",
};

client.updateAppSettings({ firebase_config });

How to Migrate to Push v2?

Migration is simple. It can be done via API or in the dashboard as below:

Migrate using the API

Set version to v2 and provide any provider config you want to use.

Firebase

Firebase requires a service account configuration because Stream uses Firebase Admin SDK in the backend.

APN

APN supports only token-based authentication unlike v1, which supports both.p12 certificate and token-based authentication. Certificate-based authentication is currently deprecated by Apple, v2 follows the new standard.

client.updateAppSettings({
  push_config: {
    version: "v2",
  },
  firebase_config: {
    credentials_json: fs.readFileSync(
      "./my_firebase_service_worker.json",
      "utf-8",
    ),
  },
  apn_config: {
    auth_type: "token",
    auth_key: fs.readFileSync("./my_apn_auth_key.p8", "utf-8"),
    key_id: "my_key_id",
    team_id: "my_team_id",
    bundle_id: "my_bundle_id",
  },
  huawei_config: {
    id: "my_huawei_app_id",
    secret: "my_huawei_app_secret",
  },
  xiaomi_config: {
    package_name: "my_xiaomi_package_name",
    secret: "my_xiaomi_app_secret",
  },
});

Migrate using Dashboard

1. Tap on the Upgrade button in the call-out

If your application is currently on v1, you will see a call to action at the top of the chat overview section and your APN and Firebase configuration will be marked as legacy.

2. Enter your configuration credentials

At this point you should see a modal. Enter your configuration for the given push provider. Upon validation and saving, your app will be upgraded to v2.

Do I need to change my Huawei and Xiaomi settings?

Huawei and Xiaomi use the same configuration in v1 and v2 so you do not need to make any changes.