Open Radar

 
Summary:
It's unclear from the APNs documentation what units to expect when dealing with timestamps. The APNs protocol deals with timestamps in two places:

1. The `apns-expiration` header sent from the APNs provider to the APNs server to indicate when a notification should no longer be sent to the destination device.
2. The `timestamp` field in the payload sent from the server to the provider when a notification is rejected because the destination device has un-registered for push notifications.

The "Notification API" docs (https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/APNsProviderAPI.html#//apple_ref/doc/uid/TP40008194-CH101-SW15) say that the `apns-expiration` header is:

> A UNIX epoch date expressed in seconds (UTC).

…but it describes the `timestamp` payload field as:

> …the last time at which APNs confirmed that the device token was no longer valid for the topic.

Note that the latter does not specify units. Reasonable minds might conclude that the `timestamp` field will be provided in seconds (particularly since this was the case in the pre-HTTP/2 versions of the APNs protocol), but in practice, the timestamps are actually sent as MILLISECONDS since the epoch. An example response from the server:

```
{"reason":"Unregistered","timestamp":1454948015990}
```

I think the problem here is two-fold:

1. If `apns-expiration` and `timestamp` have different units, both should have their units called out explicitly.
2. Is it possible that the units for `apns-expiration` have changed and that the docs are out of date? Providers have no way of knowing how that values they send for the `apns-expiration` header are being interpreted by the server.

Steps to Reproduce:
n/a

Expected Results:
The APNs documentation should clearly state the units for all timestamps, especially if they do not all use the same units.

Actual Results:
The APNs documentation only calls out units for one of two timestamp fields, and the second timestamp field appears to use different units in practice.

Version:
Local and Remote Notification Programming Guide - Notification API (https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/APNsProviderAPI.html#//apple_ref/doc/uid/TP40008194-CH10)

Notes:
Please see https://github.com/relayrides/pushy/issues/237 for a real-world example of a misinterpretation of units.

Configuration:
n/a

Attachments: