The SDKs and APIs

Urban Airship has SDKs for the iOS, Android/Amazon, Windows, and Web platforms, as well as three major APIs. The APIs correspond to our Engage (messaging), Reach (passes), and Connect (event stream) products.

SDK Uses

The SDK registers channels and interprets notifications sent from Urban Airship. You must integrate the SDK with your app or website in order to issue notifications to your mobile and/or web audiences. Devices that have installed your app and web browsers that have opted-in are eligible to receive notifications. Refer to your app's platform documentation for help integrating and using the SDK.

API Uses and Base URLs

Most features for messages and passes are available via the APIs, however some are available only from the dashboard Dashboard- and API-only exceptions are noted throughout the docs. See API vs Dashboard below for more information.

Engage API
Create and send messages to users, and use advanced messaging features like Automation. Because this API encompasses the majority of the Urban Airship feature set, this is sometimes referred to as the Urban Airship API.

Base URL: https://go.urbanairship.com

Reach API
Create Apple Wallet and Google Pay passes and adaptive links.

Base URL: https://wallet-api.urbanairship.com

Note

While the Reach API can be used to create pass templates and URLs, passes are not distributed to recipients via the Reach API. See: Pass Distribution Methods.

Connect API
Access your app's event stream, helping you gather information about user interactions with your notifications and app. With Connect, you have access to the data that will help you maximize the effectiveness of your communications.

Base URL: https://connect.urbanairship.com

Channel Registration

Urban Airship's SDK and Engage API are fundamental to the platform, as they are the mechanisms for registering channels. Channel registration is a basic requirement for sending notifications; you cannot send notifications to a channel that is not registered or in the process of becoming registered.

SDK vs API

The SDK enables communications with mobile devices and web browsers; it makes devices and browsers Urban Airship clients. You will bundle the SDK with your app or website to register and issue notifications to mobile devices and web browsers.

The API is how you will register non-native platforms, like SMS and email, and provides access to the complete Urban Airship feature set — including open channels, custom events, the event stream, etc. In the case of platforms for open channels, you will also need a webhook server that can interpret /push payloads.

Registration Requirements

This table represents the minimum requirements for communicating with the various platforms supported by Urban Airship. A channel must either have installed the SDK or be registered via the API.

Channel TypeAPI RegistrationSDK Registration
Android
iOS
Amazon
Windows
Web Browser
Email
SMS
Open Channel

Authentication

Urban Airship APIs all require one of the authentication methods below. Some endpoints allow multiple authentication schemes. In general, your app should use Basic App authentication, and server-side implementations should use Bearer over Basic Master authentication where available. See also: App Keys & Secrets: Security.

Auth TypeValuePlatformDescription
Basic AppApp Key and App Secret, Base64 encoded
  • Engage
  • Connect
  • Reach
The typical authentication scheme for apps integrating with Urban Airship. Basic App authentication is limited to low-security API endpoints, ensuring that users can't compromise your data with your app in the wild.
Basic MasterApp Key and Master Secret, Base64 encoded
  • Engage
  • Connect
Grants access to the complete Engage API and should be reserved for server-to-server communications only. You should not give out your App Master Secret or use Basic Master authorization with your app.
BearerBearer Token
  • Engage
Bearer authentication uses a token that you can create and revoke via the dashboard. Because you can create and revoke tickets for your team at will, bearer authentication maximizes your control over who can access the API via your app.

API vs Dashboard

It may be helpful to think of Urban Airship APIs as an expansion of the dashboard feature set. You can do almost anything via the API that you would do using the dashboard — with notable additions, such as:

  • Use the custom-events endpoint to associate external data with channels and users.
  • Open an event stream with the Connect API to determine the effectiveness of your notifications.
  • Use open-channels to communicate with channels and platforms that aren't natively supported by Urban Airship.
Note

Some API endpoints may be restricted by your Urban Airship feature bundle. Contact your Account Manager if you do not have access to an endpoint or feature that you want to take advantage of.

Engage

The Engage API and dashboard support similar functionality, with some differences in terminology between the two. The tables below map message types, workflow types, and features to their respective API objects and endpoints.

Message Types

See Message and Workflow Types for message type definitions.

Message TypeDashboardAPI objectRequires SDK
Push Notification"notification": {}
Silent Push Notification"notification": {}
Web Push Notification"notification": { "web": {}}
In-App Message"in_app": {} 1
Message Center"message": {}
Apple News NotificationNot supported
Email Notification"notification": { "email": {}}
SMS Notification2"notification": { "sms": {}}

1 There is currently no server API for In-App Automation.
2 SMS notifications cannot be combined with other message types in the dashboard.

Workflows

A workflow is a method of creating messages via the dashboard. See Message and Workflow Types for definitions of each and to learn which message types can be used with each workflow and API endpoint.

Workflow TypeDashboardAPI endp int
Message/push
A/B Test/experiments
Automation/pipelines
In-App AutomationNot supported
Apple NewsNot supported

Features

Some features, e.g., tags and named users, can be set via the API (server-side) or the SDK (device-side) but not via the dashboard.

FeatureDashboardAPI endpoint
Email Channel registration/channels/email
SMS Channel registration/channels/sms
Open Channel registration1/channels/open
Named Users2/named-users
Tags2various
Segments/segments
Lists/static-lists
Custom Events/custom-events
Reports/reports
Location

1 Open Channels require a webhook server that will accept a /push payload.
2 Named users and tags can be set client-side, via the SDK.

Reach

The Reach API has a similar feature set to the dashboard. In addition to dashboard functionality, you can also use the Reach API to create callbacks using webhooks for pass events, like pass installation and uninstallation.

Reach template and pass payloads are largely based on Apple Wallet and Google Pay specifications. Passes for each platform have similar objects, but the arrangement of objects on the pass differs by pass type. See the Pass Reference for more information about pass layouts.

Because passes typically include fields that must be updated dynamically and programmatically, e.g., by user, location, or as other events occur, it can be helpful to create and manage your passes through the API.

Connect

Connect is an API-only feature. The Connect API consists of a single endpoint that opens a real-time event stream for an Engage project. You can authorize Connect streams for various apps via the dashboard, but you can only access a Connect event stream via the API.

The event stream reflects user actions, changes in device environment, e.g., encountering beacons, and server-side actions, e.g., sending push notifications. You can use the event stream to gather information about how users use your app and determine effectiveness of your communications with your users.

When you make a call to the Connect API, you can set the criteria that determines the events the stream will return. See the Connect API Reference for help with opening and filtering the event stream.