API : CardDAV : Push notifications

Introduction

Apple devices do not poll a CardDAV server often. To make a change show up on the phone within seconds instead of at the next poll, the server implements the Apple Push extension to CardDAV: each address book advertises how to subscribe, the device registers its APN token, and the server sends a silent push whenever something in that book changes. The device then does its normal PROPFIND and picks up the change.

Only Apple clients use this. DAVx5, Thunderbird and the rest poll on the CTag, which works just as well, only slower.

APNS topic	`web.dk.telecomx.carddav`
Environment	`PRODUCTION`
Push key	`<employeeId>/<bookType>`, e.g. `1234567890ABCDEF12345678/personal`
Subscriptions	Mongo collection `PbxCardDavSubscriptions`

Advertising

A PROPFIND on an address book collection returns two extra properties in the CalendarServer namespace (http://calendarserver.org/ns/):

<CS:push-transports>
  <CS:transport type="APNS">
    <CS:subscription-url>
      <D:href>/carddav/addressbooks/1234567890ABCDEF12345678/personal/</D:href>
    </CS:subscription-url>
    <CS:apsbundleid>web.dk.telecomx.carddav</CS:apsbundleid>
    <CS:env>PRODUCTION</CS:env>
  </CS:transport>
</CS:push-transports>
<CS:pushkey>1234567890ABCDEF12345678/personal</CS:pushkey>

These two are only returned when the client actually asks for them - they are left out of an allprop response.

Subscribing

The device POSTs an XML body with its APN device token to the subscription URL, which is the address book collection itself.

URL	https://api.telecomx.dk/carddav/addressbooks/{employeeId}/{book}/
Method	POST
Body	XML containing the device token. A `<unsubscribe>` element anywhere in the body makes it an unsubscribe; anything else is a subscribe.

Response
201 Created	Subscribed. The subscription is upserted on employee + device token + book, so a repeated subscribe just refreshes it.
200 OK	Unsubscribed.
400	No device token found in the body.

Every subscribe also opportunistically deletes subscriptions that have not been refreshed for 30 days, so devices that are wiped or lose the account clean themselves out.

What triggers a push

Book	Triggered by
`personal`	The employees own phonebook contact created, updated or deleted - from a device, from the REST API or from an MS365 sync through /carddav/notify.
`shared`	A phonebook contact without an owner created, updated or deleted.
`colleagues`	An employee created or deleted; an employee updated where `name`, `title`, `department`, `emailAddress`, `picture` or `state` changed; a PBX extension created or updated; an MVNO account created with an extension, or saved while it is - or was until just now - linked to one.

Presence changes deliberately do not push - employees change presence constantly and none of it is in the vCard.

Pushes are sent as silent notifications carrying the push key, grouped so one send covers every device on the same key. A device token that APNS rejects is deleted from the subscriptions right away. A failing push is logged and otherwise ignored: it must never make the change that caused it fail.

Sending a push from another service

Any service that writes contacts straight to the database, rather than through the API, has to trigger the push itself with POST /carddav/notify.

WIKI

Table of Contents