Managing users and devices

Before your app can receive notifications on a user's device, the app's code will need to register the device with both the API BaaS and the appropriate push notification service (Apple APNs or Google GCM).

By registering with the API BaaS, your app adds the device on which it is installed to your data store. The device is represented as a Device entity. This makes it possible for you to target that device when sending notifications. (For more on the Device entity, see Default Data Entity Types.) Any devices, users, and groups that have been registered in this way may be targeted with push notifications.

By registering with the notification service, you make the device known to the service. This way, the service can forward your notifications to the device.

Registering devices

The following samples illustrate how to register a device with a notification service and with the API BaaS. At a high level, your code will send a registration request to the notification service, then use information in the service's response to send a separate request to the API BaaS. The two requests correlate the notification service, API BaaS, and your mobile app.

You can also create device entities separately by using the /devices endpoint. For more information on using the /devices endpoint in the API BaaS, see the Device entity reference.

Registering a device with a notification service is a standard coding activity for implementing push notifications. This is not specific to the API BaaS.

The following code illustrates how you can use the iOS SDK to register a device with both the Apigee server and with the APNs, the Apple push notification service. This example assumes that your code has already property initialized the SDK. For more information, see Installing the Apigee SDK for iOS.

// Register with Apple to receive notifications.
// Invoked when the application moves from an inactive to active state. Use this
// method to register with Apple for notifications.
- (void)applicationDidBecomeActive:(UIApplication *)application
{
// Find out what notification types the user has enabled.
UIRemoteNotificationType enabledTypes =
[application enabledRemoteNotificationTypes];
// If the user has enabled alert or sound notifications, then
// register for those notification types from Apple.
if (enabledTypes & (UIRemoteNotificationTypeAlert|UIRemoteNotificationTypeSound)) {
// Register for push notifications with Apple
NSLog(@"registering for remote notifications");
[application registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert |
UIRemoteNotificationTypeSound];
}
}
// Invoked as a callback from calling registerForRemoteNotificationTypes.
// newDeviceToken is a token received from registering with Apple APNs.
// Use this method to register with Apigee.
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)newDeviceToken
{
// Register device token with the API BaaS (will create the Device entity if it doesn't exist)
// Sends the name of the notifier you created with Apigee, along with the token your code
// received from Apple.
ApigeeClientResponse *response = [dataClient setDevicePushToken: newDeviceToken
forNotifier: notifier];
if ( ! [response completedSuccessfully]) {
[self alert: response.rawResponse title: @"Error"];
}
}
// Invoked as a callback from calling registerForRemoteNotificationTypes if registration
// failed.
- (void)application:(UIApplication*)application didFailToRegisterForRemoteNotificationsWithError:(NSError*)error
{
[self alert: error.localizedDescription title: @"Error"];
}

Initialize the Apigee client and check for notifications that might have been sent while the app was off.

The following code illustrates how to register a client device with GCM, register the device with Apigee, and associate the device with the user. Methods used in this code are defined in the Apigee Android SDK. For more information on downloading and installing the SDK, see Installing the Apigee SDK for Android.

The following code illustrates how you can use the JavaScript functions included with the PhoneGap plugin to register a device with both the Apigee server and with the APNs, the Apple push notification service.

// Declare a variable for calling push notification APIs.
var pushNotification = window.plugins.pushNotification;
// Collect configuration options to specify that this device accepts
// an alert message, an application badge, and a sound.
var appleOptions = {
alert:true, badge:true, sound:true
};
// Register the device with the API BaaS, passing options for configuration
// along with a callback from which you can retrieve the device token
// sent by Apigee.
pushNotification.registerDevice(appleOptions, function(status) {
console.log(status);
// If a token was received, bundle options to pass when registering the device
// with the push notification service. The provider value must be "apigee" to
// support push notification through Apigee. orgName and appName should be
// values corresponding to those used in your Apigee account.
// notifier is the unique name you associated with the Apigee notifier you created.
// token is the device token this code received from Apigee after registering the
// device.
if(status.deviceToken) {
var options = {
"provider":"apigee",
"orgName":"YOUR APIGEE.COM USERNAME",
"appName":"sandbox",
"notifier":"YOUR NOTIFIER",
"token":status.deviceToken
};
// Use the device token and other options to register this device with the
// push notification provider.
pushNotification.registerWithPushProvider(options, function(status){
console.log(status);
});
}
});

The functions used in this code are defined in the PhoneGap plugin. JavaScript functions invoke underlying Objective-C or Java code (depending on platform). You'll find that code in these files, included in the Apigee PhoneGap push notification plug-in.

Connecting devices to users

You can associate user entities with device entities in the API BaaS. Doing so allows you to target your push notifications at users with specific characteristics. The following describes how to connect a user to a specific device in the API BaaS.

For more information on creating a device in your API BaaS data store, see "Registering Devices" above.

For more information on creating a user in your API BaaS data store, see User

The following code examples all use the same basic endpoint pattern for connecting devices with users:

curl

The following call connects user "joex" with device 7a0a1cba-9a18-3bee-8ae3-4f511f12a386 (the device UUID). After this connection, you can send a push notification to joex rather than the device. Further, if joex has specific properties set--such as {"favoritecolor": "blue"}--you can send a push notification to all users whose favorite color is blue (assuming they're connected to devices in the API BaaS).

The following sample code, taken from AppServices.java in the native Android push sample, uses the connectEntitiesAsync method from the Android SDK to connect a device to an authenticated user.

// connect Device to current User - if there is one
if (dataClient.getLoggedInUser() != null) {
dataClient.connectEntitiesAsync("users", dataClient.getLoggedInUser().getUuid().toString(),
"devices", device.getUuid().toString(),
new ApiResponseCallback() {...

The following code illlustrates how to associate the currently logged in user with their device.

// You'll need a client from the JavaScript SDK.
var client = new Apigee.Client({
// Initialize client.
});
// Get information about the current user so you can use
// it to connect them with their device.
client.getLoggedInUser(function(err, data, user) {
if(err) {
// Could not get the logged in user.
} else {
if (client.isLoggedIn()) {
// Using a PushNotification function to get the device ID as
// it is known to the Apigee system.
pushNotification.getApigeeDeviceId(function(results) {
if (results.deviceId) {
// Use the JavaScript SDK connect function to register
// a connection between the current user and their device.
user.connect('devices', results.deviceId, function (err, data) {
if (err) {
// Could not make the connection.
} else {
// Call succeeded, so pull the connections back down.
user.getConnections('devices', function (err, data) {
if (err) {
// Couldn't get the connections.
} else {
// Connection exists.
});
}
}
}
}
}
}
}

You can also connect users with groups so that you can send push notifications to groups of users (and their associated devices), see Working with group data.