The Apple Notification Center Service

The Apple Notification Center Service is a primary service whose service UUID is 7905F431-B5CE-4E99-A40F-4B1E122D00D0.

Only one instance of the ANCS may be present on an NP. Due to the nature of iOS, the ANCS is not guaranteed to always be present. As a result, the NC should look for and subscribe to the Service Changed characteristic of the GATT service in order to monitor for the potential publishing and unpublishing of the ANCS at any time.

Service Characteristics

In its basic form, the ANCS exposes three characteristics:

All these characteristics require authorization for access.

Support for the Notification Source characteristic is mandatory, whereas support for the Control Point characteristic and Data Source characteristic is optional.

Notification Source

The Notification Source characteristic is the characteristic upon which an NC is informed of:

  • The arrival of a new iOS notification on the NP

  • The modification of an iOS notification on the NP

  • The removal of an iOS notification on the NP

GATT notifications may be delivered as soon as the NC subscribes to the Notification Source characteristic. As a result, the NC should be in a state where it can properly accept and process these messages before subscribing to this characteristic.

The format of GATT notifications delivered through the Notification Source characteristic is shown in Figure 2-1.

Figure 2-1  The format of a GATT notification delivered through a Notification Source characteristic

A GATT notification delivered through the Notification Source characteristic contains the following information:

  • EventID: This field informs the accessory whether the given iOS notification was added, modified, or removed. The enumerated values for this field are defined in EventID Values.

  • EventFlags: A bitmask whose set bits inform an NC of specificities with the iOS notification. For example, if an iOS notification is considered “important”, the NC may want to display a more aggressive user interface (UI) to make sure the user is properly alerted. The enumerated bits for this field are defined in EventFlags.

  • CategoryID: A numerical value providing a category in which the iOS notification can be classified. The NP will make a best effort to provide an accurate category for each iOS notification. The enumerated values for this field are defined in CategoryID Values.

  • CategoryCount: The current number of active iOS notifications in the given category. For example, if two unread emails are sitting in a user’s email inbox, and a new email is pushed to the user’s iOS device, the value of CategoryCount is 3.

  • NotificationUID: A 32-bit numerical value that is the unique identifier (UID) for the iOS notification. This value can be used as a handle in commands sent to the Control Point characteristic to interact with the iOS notification.

The lifetime of an iOS notification can be implicitly deduced through the sequence of Notification Source GATT notifications generated by the NP, as shown in Figure 2-2.

Figure 2-2  The lifetime of an iOS notification

Control Point and Data Source

An NC may want to interact with an iOS notification. It may want to retrieve more information about it, including its contents, or it may want to perform actions on it. The retrieval of these attributes is performed through the Control Point and Data Source characteristics.

An NC can issue a request to retrieve more information about an iOS notification by writing specific commands to the Control Point characteristic. If the write to the Control Point characteristic is successful, the NP will promptly respond to the request through a stream of GATT notifications on the Data Source characteristic.

An NC can perform pre-determined actions on an iOS notification by writing specific commands to the Control Point characteristic. More information about actions and iOS notifications are in Perform Notification Action.

Get Notification Attributes

The Get Notification Attributes command allows an NC to retrieve the attributes of a specific iOS notification. The format of a Get Notification Attribute command is shown in Figure 2-3.

Figure 2-3  The format of a Get Notification Attribute command

A Get Notification Attributes command contains the following information:

  • CommandID: Should be set to 0 (CommandIDGetNotificationAttributes).

  • NotificationUID: The 32-bit numerical value representing the UID of the iOS notification for which the client wants information.

  • AttributeIDs: A list of attributes that the NC wants to retrieve. Some attributes may need to be followed by a 16-bit length parameter that specifies the maximum number of bytes of the attribute the NC wants to retrieve.

The format of a response to a Get Notification Attributes command is shown in Figure 2-4.

Figure 2-4  The format of a response to a Get Notification Attributes command

A response to a Get Notification Attributes command contains the following information:

  • CommandID: Set to 0 (CommandIDGetNotificationAttributes).

  • NotificationUID: The 32-bit numerical value that is the UID of the iOS notification the following attributes correspond to.

  • AttributeList: A list of AttributeIDs/16-bit Length/Attribute tuples. An attribute is always a string whose length in bytes is provided in the tuple but that is not NULL-terminated. If a requested attribute is empty or missing for the iOS notification, its length is set to 0. The tuples are always in the same order as the AttributeIDs of the Get Notification Attributes command.

If the response is larger than the negotiated GATT Maximum Transmission Unit (MTU), it is split into multiple fragments by the NP. The NC must recompose the response by splicing each fragment. The response is complete when the complete tuples for each requested attribute has been received.

Get App Attributes

The Get App Attributes command allows an NC to retrieve attributes of a specific app installed on the NP. The format of the Get App Attributes command is shown in Figure 2-5.

Figure 2-5  The format of a Get App Attributes command

A Get App Attributes command contains the following information:

  • CommandID: Should be set to 1 (CommandIDGetAppAttributes).

  • AppIdentifier: The string identifier of the app the client wants information about. This string must be NULL-terminated.

  • AttributeIDs: A list of attributes the NC wants to retrieve.

The format of a response to a Get App Attributes command is shown in Figure 2-6.

Figure 2-6  The format of a response to a Get App Attributes command

A response to a Get App Attributes command contains the following information:

  • CommandID: Set to 1 (CommandIDGetAppAttributes).

  • AppIdentifier: The string identifier of the app the following attributes correspond to. This string is NULL-terminated.

  • AttributeList: A list of AttributeIDs/16-bit Length/Attribute tuples. An attribute is always a string whose length in bytes is provided in the tuple but that is not NULL-terminated. If a requested attribute is empty or missing for the app, its length is set to 0. The tuples are always in the same order as the AttributeIDs of the Get App Attributes command.

As with a response to a Get Notification Attributes command, if the response to a Get App Attributes command is larger than the negotiated GATT Maximum Transmission Unit (MTU), it is split into multiple fragments by the NP. The NC must recompose the response by splicing each fragment. The response is complete when the complete tuples for each requested attribute has been received.

Perform Notification Action

The Perform Notification Action command allows an NC to perform a predetermined action on a specific iOS notification. A Perform Notification Action command contains the following fields:

Bytes

Name

Description

1

CommandID

Set to 2 (CommandIDPerformNotificationAction).

2-5

NotificationUID

A 32-bit numerical value representing the UID of the iOS notification on which the client wants to perform an action.

6

ActionID

The desired action the NC wants to be performed on the iOS notification.

No data is generated on the Data Source characteristic when this command is issued, whether it is successful or not.

Notification Actions

Starting with iOS 8.0, the NP can inform the NC of potential actions that are associated with iOS notifications. On the user’s behalf, the NC can then request the NP to perform an action associated with a specific iOS notification.

The NC is informed of the existence of performable actions on an iOS notification by detecting the presence of set flags in the EventFlags field of the GATT notifications generated by the Notification Source characteristic:

  • EventFlagPositiveAction: A positive action exists and is associated with this iOS notification.

  • EventFlagNegativeAction: A negative action exists and is associated with this iOS notification.

The actual actions performed by the NP on behalf of the NC are determined by the NP and vary depending on the iOS notification they are performed on. For example, performing a positive action on an Incoming Call notification may answer it, while performing a negative action may decline it.

The NC must neither assume nor try to guess in advance the exact action performed on an iOS Notification, because these actions are based upon information unavailable to it, as well as other factors such as the ANCS version implemented by the NP. The NP guarantees that positive and negative actions are associated with results that do not surprise the user.

If present for an iOS notification, positive and negative actions may be represented to the user as check marks, X marks, or colors commonly associated with acknowledgment and dismissal (such as green and red).

The NC can retrieve labels that succinctly describe the actual actions associated with an iOS notification by retrieving new notification attributes introduced in iOS 8.0:

  • NotificationAttributeIDPositiveActionLabel: The label used to describe the positive action that can be performed on the iOS notification.

  • NotificationAttributeIDNegativeActionLabel: The label used to describe the negative action that can be performed on the iOS notification.

Sessions

An ANCS session begins when an NC subscribes to the Notification Source characteristic on an NP and ends when the NC either unsubscribes from the same characteristic or disconnects from the NP. Because the ANCS is not designed to be a complete synchronization service, it does not keep track of state across sessions. As a result, all identifiers (such as NotificationUID and AppIdentifier) and all data exchanged between an NC and an NP are valid only within a particular session.

When a particular session ends, the NC should remove any identifiers and data it gathered and stored during the session. When a new session begins, the NP does its best to inform the NC of any existing iOS notifications on the system. The NC can use this information to build a model to use for the remainder of the session.

Attribute Fetching and Caching

It is strongly recommended for an NC to fetch attributes only as needed and possibly in response to user actions. For example, if an NC chooses to display active iOS notifications in a simple list, and to show only details about a specific iOS notification when selected by the user, then the retrieval of this iOS notification’s attributes can be triggered lazily.

During a session, it is strongly recommended that an NC build a cache of App Attributes for each app identifier it encounters. Building this cache allows the NC to avoid retrieving the same immutable App Attributes multiple times—saving time and preserving battery.

Error Codes

When writing to the Control Point characteristic, an NC may receive the following ANCS-specific error codes:

  • Unknown command (0xA0): The commandID was not recognized by the NP.

  • Invalid command (0xA1): The command was improperly formatted.

  • Invalid parameter (0xA2): One of the parameters (for example, the NotificationUID) does not refer to an existing object on the NP.

  • Action failed (0xA3): The action was not performed.

If the NP replies with an error, it will not generate any GATT notification on the Data Source characteristic for the corresponding command.

Example Diagrams

The following two figures show examples of two common interactions between an NP and an NC. Figure 2-7 shows the typical sequence of commands and responses needed to set up the ANCS on an NC. Figure 2-8 shows the typical sequence of commands and responses needed to get more information about an iOS notification in order to display it on an NC.

Figure 2-7  Service setup example
Figure 2-8  Notification attribute retrieval example


Copyright © 2014 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2014-10-20