Push Templates Confused about "Push Templates"?
Let us know how we can improve our documentation:
Confused about "Push Templates"?
Let us know how we can improve our documentation:
For both Firebase and APN, the payload that is being sent is rendered using the handlebars templating language, to ensure full configurability for your app.
Stream provides the following variables in the template rendering context:
Context VariablesCopied!Confused about "
Context Variables"?
Let us know how we can improve our documentation:
Confused about " Context Variables"?
Let us know how we can improve our documentation:
Name | Type | Description |
---|---|---|
channel | object | Channel object. You can access the channel name and any other custom field you have defined for this channel |
sender | object | Sender object. You can access the user name, id or any other custom field you have defined for the user |
receiver | object | Receiver object. You can access the user name, id or any other custom field you have defined for the user |
message | object | Message object. You can access the text of the message (or a preview of it if the message is too large) or any other custom field you have defined for the message |
members | array | Channel members. You can access the user name, id and any other custom field of each member (i.e. excluding sender) |
otherMembers | array | Like members but the user who will be receiving the notification is excluded (i.e. excluding sender and receiver) |
unread_count | integer | Number of unread messages |
unread_channels | integer | Number of unread channels for this user |
DefaultsCopied!Confused about "Defaults"?
Let us know how we can improve our documentation:
Confused about "Defaults"?
Let us know how we can improve our documentation:
When editing APN/Firebase settings, if you leave the notification_template
or data_template
field empty, default templates will be used.
APN default:
1
2
3
4
5
6
7
8
9
10
{
"aps" : {
"alert" : {
"title" : "{{ sender.name }} @ {{ channel.name }}",
"body" : "{{ message.text }}"
},
"badge": {{ unread_count }},
"category" : "NEW_MESSAGE"
}
}
Firebase default notification template:
1
2
3
4
5
6
{
"title": "{{ sender.name }} @ {{ channel.name }}",
"body": "{{ message.text }}",
"click_action": "OPEN_ACTIVITY_1",
"sound": "default"
}
Firebase default data template:
1
2
3
4
5
6
7
8
{
"sender": "{{ sender.id }}",
"channel": {
"type": "{{ channel.type }}",
"id": "{{ channel.id }}"
},
"message": "{{ message.id }}"
}
LimitationsCopied!Confused about "Limitations"?
Let us know how we can improve our documentation:
Confused about "Limitations"?
Let us know how we can improve our documentation:
There are some limitations that Stream imposes on the push notification handlebars template to make sure no malformed payloads are being sent to push providers.
1: Custom Arrays Can't Be IndexedCopied!Confused about "1: Custom Arrays Can't Be Indexed"?
Let us know how we can improve our documentation:
Confused about "1: Custom Arrays Can't Be Indexed"?
Let us know how we can improve our documentation:
For example, given the context:
1
2
3
4
5
6
{
"sender":{
"name": "Bob",
"some_array": ["foo","bar"]
}
}
And the template:
1
"title": {{sender.some_array.[0]}}
The rendered payload will be:
1
"title": ""
2: Interpolating Whole Lists and Objects Isn't AllowedCopied!Confused about "2: Interpolating Whole Lists and Objects Isn't Allowed"?
Let us know how we can improve our documentation:
Confused about "2: Interpolating Whole Lists and Objects Isn't Allowed"?
Let us know how we can improve our documentation:
For example, given the context:
1
2
3
4
5
6
7
8
9
{
"sender":{
"name": "bob",
"some_array": ["foo","bar"],
"address": {
"street": "willow str"
}
}
}
And the template:
1
"title": "{{ sender.some_array }} {{ sender.address }}"
The rendered payload will be:
1
"title": "[] {}"
3: Unquoted fields that aren't in the context will be rendered as empty stringsCopied!Confused about "3: Unquoted fields that aren't in the context will be rendered as empty strings"?
Let us know how we can improve our documentation:
Confused about "3: Unquoted fields that aren't in the context will be rendered as empty strings"?
Let us know how we can improve our documentation:
For example, given the context:
1
2
3
4
5
{
"sender":{
"name": "bob"
}
}
And the template:
1
"title": {{ sender.missing_field }}
The rendered payload will be:
1
"title": ""
Advanced Use CasesCopied!Confused about "Advanced Use Cases"?
Let us know how we can improve our documentation:
Confused about "Advanced Use Cases"?
Let us know how we can improve our documentation:
For advanced use cases (e.g. A list of channel members in the notification title, conditional rendering, etc), Stream provides some handlebars helper functions.
Helper FunctionsCopied!Confused about "Helper Functions"?
Let us know how we can improve our documentation:
Confused about "Helper Functions"?
Let us know how we can improve our documentation:
name | type | description |
---|---|---|
implodemembers | function | takes the list of channel members and implodes it into a single string, using a custom limit, separator and suffix. |
json | function | renders passed parameter as JSON (e.g |
each | function | For loop. Use |
if | function | If function. Tests trueness of given parameter. Supports else statement. (e.g |
unless | function | Unless function. Tests falseness of given parameter. Supports else statement. (e.g |
equal | function | Equality check function. Tests equality of the given 2 parameters. Supports else statement. (e.g |
unequal | function | Inequality check function. Tests inequality of the given 2 parameters. Supports else statement. (e.g |
ifLt | function | If less than. Supports else statement. |
ifLte | function | If less than or equal. Supports else statement. |
ifGt | function | If greater than. Supports else statement. |
ifGte | function | If greater than or equal. Supports else statement. |
remainder | function | Calculates the difference between the length of an array and an integer (e.g |
Most of the functions above are straight forward, except for implodeMembers
, which will be detailed further.
The full function signature is: {{implodeMembers otherMembers|members [limit=] [separator=] [nameField=] [suffixFmt=]}}
Function ParametersCopied!Confused about "Function Parameters"?
Let us know how we can improve our documentation:
Confused about "Function Parameters"?
Let us know how we can improve our documentation:
name | type | description | default |
---|---|---|---|
otherMembers | members | array | Which member array to implode | |
limit | integer | How many member names to show before adding the suffix | 3 |
nameField | string | Field name from which field to retrieve the member's name. Note: does not support nesting | name |
separator | string | Separator to use for channel members | , |
suffixFmt | string | Format string to use for the suffix. Note: only %d is allowed for formatting | and %d other(s) |
ExamplesCopied!Confused about "Examples"?
Let us know how we can improve our documentation:
Confused about "Examples"?
Let us know how we can improve our documentation:
Let's put these helpers to use in a few examples:
Example 1Copied!Confused about "Example 1"?
Let us know how we can improve our documentation:
Confused about "Example 1"?
Let us know how we can improve our documentation:
Rendering channel members in the notification title. Each member's name is stored in the fullName
field.
What we want to achieve:
1
2
3
4
5
6
7
8
9
{
"aps": {
"alert": {
"title": "Bob Jones, Jessica Wright, Tom Hadle and 4 other(s)",
"body": "Bob Jones: Hello there fellow channel members"
},
"badge": 0
}
}
How we will achieve it: using implodeMembers
with a custom name field (leaving others empty so that defaults will be used):
1
2
3
4
5
6
7
8
9
{
"aps": {
"alert": {
"title": "{{implodeMembers otherMembers nameField="fullName"}}",
"body": "{{ sender.fullName }}: {{ message.text }}"
},
"badge": {{ unread_count }}
}
}
Example 2Copied!Confused about "Example 2"?
Let us know how we can improve our documentation:
Confused about "Example 2"?
Let us know how we can improve our documentation:
Rendering channel members in the notification title. Each member's name is stored in the nested details.name
field.
What we want to achieve:
1
2
3
4
5
6
7
8
9
{
"aps": {
"alert": {
"title": "Bob Jones, Jessica Wright, Tom Hadle and 4 other(s)",
"body": "Bob Jones: Hello there fellow channel members"
},
"badge": 0
}
}
How we will achieve it: since implodeMembers
doesn't support nested fields, we need to use a bunch of helpers such as each
, ifLte
. Note how the use of ~
will trim the whitespaces so that the title in rendered in a single row:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"aps": {
"alert": {
"title": "
{{~#each otherMembers}}
{{#ifLte @index 2}}
{{~this.details.name}}{{#ifLt @index 2 }}, {{/ifLt~}}
{{~else if @last~}}
{{{ " " }}} and {{remainder otherMembers 3}} other(s)
{{~/ifLte~}}
{{/each~}}",
"body": "{{ sender.details.name }}: {{ message.text }}"
},
"badge": {{ unread_count }}
}
}