Push #

View this page as Markdown

On this page

Push lets your application's backend send a notification to your users' phones and tablets. Turn Zero Cloud delivers it to iPhones through Apple and to Android devices through Google. Your backend lists the users or the devices, and the platform finds each device your app registered.

This package is your backend's side of that service. Its client sends one message under your application's platform credential. It reports what the platform accepted from the send, and it throws a typed refusal that includes the platform's refusal name.

Use it when #

Use Push when your backend must tell a signed-in user something while the app is closed: a game ended, an order shipped, a turn is waiting. Your app must sign its users in through your application's realm and register each device after sign-in. Send push notifications covers the credentials, the declaration, the device registration, and the send route.

Do not use it for a web page in a browser or for a text message. Neither is offered.

What it provides #

  • A client, createPushClient, which The client describes. The module has no dependencies and keeps no state.
  • A send to users. The method send(users, message) sends one message to every registered device of the named users. The user identifier is the one the realm returns for the signed-in user.
  • A send to devices. The method sendToDevices(installations, message) sends one message to the named installations, the identifiers your app registered its devices under.
  • The response. Each send returns messageId, accepted (the count of deliveries queued), and unknownUsers or unknownDevices, the users or devices that had no registration.
  • A typed refusal. Any other response makes the send throw a PushRefusal. Its refusal member is the platform's refusal name, and members contains the refusal's other values.
  • A test double, createPushDouble at @turnzero/push/testing, which responds to a send as the platform does and records every send. Test with the double shows it in use.
Message member Required What it contains
notification.title Yes Up to 256 characters.
notification.body Yes Up to 4,000 characters.
notification.badge No The count on the app's icon.
notification.sound No A sound the app bundles, or default.
data No String values for the app, at most 4,096 bytes serialized. The key aps is reserved.
ttlSeconds No How long an offline device's notification is kept, a day by default and four weeks at most.
collapseId No An identifier the provider uses to combine notifications. It does not prevent every duplicate delivery.
priority No high by default, or normal.

Availability #

Version 0.5.4 is the package's current version, and this page describes it. Until the library's next publish, read_library can return an earlier version without every change described here. Use the version it returns.

The entry includes the testing subpath. It also contains the compiled modules, the product statement and detailed contract, and the integration guide. Turn Zero Cloud runs the push service. Call read_push to see device counts, the last hour's outcomes, and the month's count against the application's push ceiling.

Account signs users in and tells your backend who they are. Secrets stores the Apple key and the Google service-account file by name. Logging records the delivery counters and one line per delivery.

The client #

The package is published in the library as the npm package @turnzero/push, not on the npm registry; Use the library installs it with one line. Send from the backend shows a send from a backend route, and a test runs it.

The function createPushClient(options) builds the client from one of two forms:

Option Meaning
api, token The platform's origin and the application's platform credential, from TURNZERO_CLOUD_API and TURNZERO_CLOUD_APP_TOKEN.
environment development or production, the environment header's value, where a credential needs one. The platform credential takes none, and the route refuses a value that contradicts it.
fetch The fetch-shaped function the client sends through, the global fetch by default.
transport In place of api and token: a function of your own, (path, init), that adds the origin and the credential, such as the test double's transport.

Give transport, or api and token, never both. When you build the client with both forms, without a token, or with an api that is not an http or https address, it throws PushClientError, code client_options. The two sends, send(users, message, { signal }) and sendToDevices(installations, message, { signal }), return a promise of { messageId, accepted, unknownUsers, unknownDevices }. A send the platform refuses rejects with PushRefusal; Refusals lists its members and names.

Refusals #

Branch on the refusal's name, never on its message. A PushRefusal has refusal, status, detail, and members. These are the refusals a send meets most often; the refusals page lists all of the platform's refusals, with the cause and remedy of each.

Refusal Status Meaning
invalid_request 400 A member of the message is malformed, and the detail identifies it; or a member contains a NUL character (U+0000) or an unpaired UTF-16 surrogate, which the detail identifies instead.
end_user_credential_not_admitted 403 The request used an end-user session. The platform refuses it before checking the push route itself.
platform_credential_required 403 The send request used a session or a minted token.
push_not_configured 409 The environment has no provider configured.
realm_not_declared 404 The application declares no accounts service.
usage_over_quota 429 The send would pass the application's monthly push ceiling.
push_answer_unreadable As received The response does not confirm whether the notification was queued. Read tzcloud_read_push to check recent outcomes. Do not retry automatically: the person could receive the notification twice.

A send refused usage_over_quota queued nothing. Its members give the month's count, the ceiling, and the send's own deliveries.

What an application must do #

Set the service up as Send push notifications describes in its steps 1 to 4, and register each device from your app after sign-in.

Send once for each event. The client does not retry: if a response is lost, the platform may already have queued the notification. A collapseId lets the provider combine notifications, but does not make resending safe.

Keep a refused send from failing the request that made it. Record the refusal, and respond to the request.

Test with the double #

The factory createPushDouble(options) from @turnzero/push/testing responds to a send as the platform does, from the devices and the monthly quota the test gives it. Build the client with createPushClient({ transport: double.transport }), or pass double.fetch as the client's fetch. Register devices with double.register(device), and read what was sent in double.sends. A test runs this sample over the double.

import assert from 'node:assert/strict';
import { createPushClient, PushRefusal } from '@turnzero/push';
import { createPushDouble } from '@turnzero/push/testing';

// A monthly allowance of one delivery, and one registered phone.
const push = createPushDouble({ quota: 1 });
push.register({ installation: 'phone-1', user: 'user-1', platform: 'ios' });
const client = createPushClient({ transport: push.transport });

const sent = await client.send(['user-1', 'user-2'], { notification: { title: 'Game over', body: 'You stumped it.' } });
assert.equal(sent.accepted, 1);
assert.deepEqual(sent.unknownUsers, ['user-2']);
assert.equal(push.sends.length, 1);
// The month's one delivery is spent, so the next send is refused by name and queues nothing.
await assert.rejects(client.send(['user-1'], { notification: { title: 'Again', body: 'One more.' } }), (error) => error instanceof PushRefusal && error.refusal === 'usage_over_quota');

The double uses the push route's own refusal names, which Refusals lists. These come from the double's own setup:

Refusal Cause Remedy
push_not_configured The double was created with both providers off, providers: { apns: false, fcm: false }. Leave a provider on.
realm_not_declared The double was created with accounts: false. Leave the accounts service declared.
platform_credential_required, end_user_credential_not_admitted The double was created with credential: 'session', 'minted', or 'end_user'. Leave the credential at the default, 'platform'.
usage_over_quota The sends passed the quota the test gave. Raise quota, or reset() between tests.
A scripted name refuseNext(name) named a refusal, or failNext() an unreachable route. Assert the name the test scripted.