Using the Push API

Note this feature is being retired. For more information, see the blog post. For more information, refer to the Push Migration Guide.

The Visual Studio App Center Push (ACP) service offers two ways to send notifications to registered devices:

• Using the App Center Portal
• Using the App Center Push API (described in this document)

When sending notifications through App Center, you can target destination devices (notification recipients) in the following ways:

• All registered devices: Send notifications to all registered devices.
• Audiences: Send notifications to a segment of your app’s registered device audience. Build audiences based on a set of device and custom properties either using the App Center Portal or through the REST API
• Device list: Send notifications to up to 100 devices (using the install IDs for the target devices).
• User list: Send notifications to up to 100 users using a list of unique user identifiers provided to App Center through the App Center SDK (Android SDK example).

All notifications sent using the App Center Push API are limited to a target audience of 1,000 devices.

Before jumping in to the Push API, spend a few minutes reviewing the App Center API documentation, it contains useful information like how to obtain the API token you need to use the Push API and how to authenticate to the service when consuming the APIs. Next, refer to the App Center Push API (Swagger) for the complete list of Push APIs (shown in the following figure); those APIs are covered in this document.

In the Push API calls, the owner_name property is either the app owner’s user id, or the name of the org the app falls under in App Center.

Requirements

App Requirements

To send notifications to a device, you must first build and deploy the client application designated to receive and process the notifications you send to the device. To do this, follow the Push SDK documentation for each target platform:

Request Requirements

Every App Center API request must include the appropriate API token in the request header. You’ll create API tokens in the App Center Account settings dialog as shown in the following figure. For information about how to generate and use an API token in an App Center API request, refer to the App Center API Introduction.

The URL used to invoke any App Center API uses your App Center app project’s app and owner names. The easiest way to retrieve these values is through the URL used to access the application in the App Center Portal. Open a browser window and navigate to https://appcenter.ms. Login to your account, then select the app with Push enabled. Take a look at the URL App Center uses when it opens the app project, it will look something like this if the app belongs to your user account:

If the app belongs to an organization, the URL will look like this:

For either example URL, the portion of the URL represented by in the example is the account or organization name. The portion of the URL represented by is the app project name.

You can also use the App Center API to retrieve an account’s user name. Open a browser window and navigate to https://openapi.appcenter.ms/#/account/users_get. Once you’ve authorized access using an API token, when you execute the API the successful result body the account name in the name property.

If the app belongs to an org, you can use the https://openapi.appcenter.ms/#/account/apps_listForOrg API to retrieve the app name. Once you’ve authorized access using an API token, populate the Organization field with the organization name and execute the API. The successful result body contains an array of apps for the organization, you’ll find the account name for each app in the array in the item’s name property.

API endpoint

The App Center API endpoint is:

The App Center Push API endpoint generally looks like the following (there are some APIs Push users will use that are published under a different service):

Where, as described in the previous section, the portion of the URL represented by in the example is the account or organization name, and the portion of the URL represented by is the app project name.

To invoke the API to send notifications, you’d build an API endpoint similar to the following:

Here’s a complete example, invoked to send notifications to users of the mycoolapp app in the joedev App Center account:

You’ll see a full example for consuming this API later in the document.

Sending notifications

The following sections illustrate how to use the App Center Push API to send notifications using the available notification options.

Notification body

Each notification sent by App Center Push must include the notification_content object; this object contains the data delivered to the target device by the platform’s push notification service (PNS).

What the target device does with the data depends on the target platform and the content of the notification_content object. Some platforms support silent notifications, where the notification is automatically passed to the target application and the app decides what to do with the data. Most notifications trigger an alert on the device and some way to view the pushed message content.

In this example:

• name : Defines the name for the notification message.
• title : Defines the title for the notification message. On target platforms where the notification is displayed in a notification area, this value displays in the title area of the notification.
• body : Defines the notification content displayed with the message.
• custom_data : Defines additional data values (formatted as a JSON object) passed to the target application running on the device. The application retrieves this data from the message and uses it in some app-appropriate way. The maximum number of characters per custom data value is 100.

Send a notification to all registered devices (broadcast)

To send a notification message, use the push/notifications API. To target all registered devices, an application submits an HTTP POST request using the following URL:

Send the body of the request in JSON format (using the application/json content type), and include the notification_content and notification_target data values shown in the example below:

Note: Available notification_target options are: [ audiences_target, devices_target, user_ids_target, account_ids_target ] . There isn’t a notification_target option for broadcast, so the application either passes in the null value, or omits the property all together.

In this example:

• name : Defines the name for the notification message.
• title : Defines the title for the notification message. On target platforms where the notification is displayed in a notification area, this value displays in the title area of the notification.
• body : Defines the notification content displayed with the message.
• custom_data : Defines additional data values (delivered as a JSON object) passed to the target application running on the device. The application retrieves this data from the message and uses it in some app-appropriate way. The maximum number of characters per custom data value is 100.

Send a notification to an Audience

Audiences allow App Center users to define a segment of an app’s user base using a set of properties (both pre-defined and custom) and send them targeted notifications. App Center allows customers to create multiple audiences in an app project (up to 200 audiences per app with a maximum of 1,000 devices per audience) and stores them for easy reuse. Developers create and manage Audiences through the App Center Portal or the App Center Analytics API, some examples of the APIs used are:

You can create groups (audiences) based on the device properties and custom properties. When defining audiences, use the following symbols to target devices using properties:

Definition	Symbol	Equivalent
equals	=	eq
not equals	!=	ne
less than	lt
greater than	>	gt
less than or equal to	le
greater than or equal to	>=	ge

The App Center SDK captures the following device properties:

• Application Version ( appVersion )
• Country ( carrierCountry )
• Device OS version ( deviceOsVersion ) — populates with API level for Android using osApiLevel , and osVersion on iOS
• DeviceModel ( model )
• Language ( locale )
• OEM ( oemName )
• Screen Size ( screenSize )

Refer to the App Center Analytics console to values collected for these properties.

Here is an example of an audience based on a device property where country is United States :

Apps set custom properties for a registered device using the App Center SDK for each target platform:

Here is an example for an audiences based two custom properties (boolean and string properties):

The JSON object uses the definition string to define the Audience selection criteria and the custom_properties object to define the property types used in the definition .

To send a notification message, use the push/notifications API. To target a specific audience, an application submits an HTTP POST request using the following URL:

Send the body of the request in JSON format (using the application/json content type), and include the notification_content and notification_target data values shown in the example below:

In this example:

• name : Defines the name for the notification message.
• title : Defines the title for the notification message. On target platforms where the notification is displayed in a notification area, this value displays in the title area of the notification.
• body : Defines the notification content displayed with the message.
• custom_data : Defines additional data values (delivered as a JSON object) passed to the target application running on the device. The application retrieves this data from the message and uses it in some app-appropriate way. The maximum number of characters per custom data value is 100.
• audiences references the list of audience names to which notifications are sent.

Send a notification to specific devices

The App Center SDK creates a unique Install ID (UUID) for each device once the app is installed. This identifier remains the same for a device when the app is updated, but a new one is generated when the app is re-installed or the user manually deletes all app data. Developers can use this unique identifier to target specific devices for notifications. The Install ID is set and maintained through the App Center SDK. To obtain the Install ID and use it to target specific devices (or installations if you want to think of it that way), you must obtain it using the App Center SDK:

The app must obtain the Install ID and send it to a backend application or database for reference when an app wants to send notifications to the device.

Assuming the following array of dummy Install IDs: [ «00000000-0000-0000-0000-000000000001», «00000000-0000-0000-0000-000000000002», «00000000-0000-0000-0000-000000000003» ] , to send a notification message to the devices, use the push/notifications API. Submit an HTTP POST request using the following URL:

Send the body of the request in JSON format (using the application/json content type), and include the notification_content and notification_target data values shown in the example below:

In this example:

• name : Defines the name for the notification message.
• title : Defines the title for the notification message. On target platforms where the notification is displayed in a notification area, this value displays in the title area of the notification.
• body : Defines the notification content displayed with the message.
• custom_data : Defines additional data values (delivered as a JSON object) passed to the target application running on the device. The application retrieves this data from the message and uses it in some app-appropriate way. The maximum number of characters per custom data value is 100.
• devices references the list of Install IDs to which notifications are sent.

Send notifications to users

User Identity set through the SDK

Many apps use proprietary methods or third-party services to authenticate users in the app. To accommodate this use case, the App Center SDK offers a method the app uses to set the captured user identifier and pass it to App Center. With this ID set, App Center can then associate users with their Analytics and Diagnostics data as well as send notifications to specific users.

To set an app user’s identity using the App Center SDK, refer to the following articles based on the target platform:

The user’s identity set through the SDK can be whatever the developer wants it to be: the user’s name, email address, phone number, or some other unique identifier.

To send a notification to one or more users, the app must set the User ID (as described above) and keep a copy of the identity later to identify target users for notifications. Developers typically store the ID in the app’s backend system for reference later.

In the following example, we’ll assume the app uses email addresses to identify users and sends a notification to the following users identities: [«james@somecomany.com», «allison@somecompany.com», «anna@somecompany.com»] . To send a notification message to the specified users, use the push/notifications API. Submit an HTTP POST request using the following URL:

Send the body of the request in JSON format (using the application/json content type), and include the notification_content and notification_target data values shown in the example below:

In this example:

• name : Defines the name for the notification message.
• title : Defines the title for the notification message. On target platforms where the notification is displayed in a notification area, this value displays in the title area of the notification.
• body : Defines the notification content displayed with the message.
• custom_data : Defines additional data values (delivered as a JSON object) passed to the target application running on the device. The application retrieves this data from the message and uses it in some app-appropriate way. The maximum number of characters per custom data value is 100.
• user_ids Defines the list of user identities (User ID) to which notifications are sent.

The App Center Push to User feature limits notifications to 100 users and up to a maximum of 1,000 target devices.