The Push Module provides your app with the ability to send push messages to Android and iOS devices. Besides the functionality to send plain text messages to your app's users, all other enabled modules are enriched with push features; other and custom modules may use the push module as well and send push messages for a variety of use cases.

images/download/attachments/27722192/db3-module-push.PNG

Configuration

GCM API Key

The GCM API key, obtained from Google (see GCM documentation)

APNS certificate password

Password for your APNS certficate.

Please note that passwordless APNS certificates are not supported.

APNS certificate

The p12 encrypted APNS certificate is obtained from Apple

A tutorial for getting APNS certificate and password in the correct format you can find here.

Proxy

You can configure a proxy either in this module configuration, or in the JVM system properties. If the proxy requires authentication, you need to configure the credentials in the module configuration, even if you configure the proxy itself via JVM system properties.

For configuring the proxy via JVM system properties, you can use as key: socksProxyHost, https.proxyHost and http.proxyHost for the host, socksProxyPort, https.proxyPort and http.proxyPort for the port, as well as http.nonProxyHosts for exclusions.

When configuring via module configuration, you have to enter the host, port and type (any one of SOCKS, HTTPS or HTTP).

Precedence

When proxy configurations are found in the module configuration, as well as in the JVM system properties, the module configuration is used. When the module configuration is empty, the configuration in the JVM system property is loaded in this order:

When using APNS: Socks, HTTPS, HTTP. As soon as a configuration is found, it's used.
When using GCM: HTTPS

Combining APNS and GCM proxy configurations

You can only enter one proxy in the module configuration, but when you want to configure different proxys for APNS and GCM (for example a Socks Proxy for APNS and a HTTPS proxy for GCM), you can use a combination of module configuration for one of the proxys and JVM system properties for the other.

Usage

The Push Module adds the attributes registrationId and deviceToken to each user object. These attributes must be set with the values of the device and the user object must be updated (saved) afterwards. Otherwise, ApiOmat can't determine which users accept push messages.

The deviceToken must be set for iPhone/iPad users
The registrationId must be set for Android users

Starting in version 2.4 it is also possible to set multiple deviceTokens and/or registrationIds for a single user. The according user properties are:

deviceTokens (for iPhone/iPad users)
registrationIds (for Android users)

Please check the documentation of Android and iOS if don’t know where you get the tokens.

When activated, the class PushMessage may be used to send push messages to other users.

For example, to send a push notification from one device to another user with the username ‘testuser’, do the following:

Android

PushMessage pushMessage = new PushMessage();
pushMessage.setPayload("A message from me");
pushMessage.setReceiverUserNames( Arrays.asList(new String[] {"testUser"}));
pushMessage.saveAsync(new AOMEmptyCallback() {
	@Override
	public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception) {
		if (exception != null) {
			// ...
		}
	}
});

iOS

AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
NSMutableArray *receivers = [[NSMutableArray alloc] init];
[receivers addObject:@"testuser"];
[pushMessage setPayload:@"A message from me"];
[pushMessage setReceiverUserNames:receivers];
[pushMessage saveAsyncWithBlock:^(NSError *error) {
}];

Swift

let pushMessage = PushMessage()
pushMessage.payload = "A message from me"
pushMessage.receiverUserNames = ["testUser"]
pushMessage.save(loadAfterwards: true) { (error) in
	if let error = error {
		//do error handling here
	}
}

JavaScript

var pushMessage= new Apiomat.PushMessage();
pushMessage.setPayload("A message from me");
pushMessage.setReceiverUserNames(["testuser"]);
 
var saveCB = {
    onOk : function() {
        console.log("saved");
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
pushMessage.save(saveCB);

You can also set the query-attribute on a PushMessage for sending a push notification to all users in your backend that fit into that query.

Media Push

The Push Module can do more than just send plain text: You can attach images and files on your push messages.

Android

PushMessage pushMessage = new PushMessage();
pushMessage.setPayload("Write your message here");
pushMessage.setReceiverUserNames( Arrays.asList(new String[] {"testUser"}));

iOS

AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
NSMutableArray *receivers = [[NSMutableArray alloc] init];
[receivers addObject:@"testuser"];
[pushMessage setPayload:@"A message from me"];
[pushMessage setReceiverUserNames:receivers];

Swift

let pushMessage = PushMessage()
pushMessage.payload = "A message from me"
pushMessage.receiverUserNames = ["testUser"]

JavaScript

var pushMessage = new Apiomat.PushMessage();
pushMessage.setPayload("Write your message here");
pushMessage.setReceiverUserName(["nameOfRecipient"]);

Now attach an image and send the push to the recipient:

Android

// Assuming you already got your image data in a byte array
pushMessage.postImageAsync(byteArray, new AOMEmptyCallback() {
   public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception) {
        // When the image is uploaded, the push message must be sent to the recipient.
        pushMessage.sendAsync(new AOMEmptyCallback() {
 
            @Override
            public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception) {
                // The Push message has been sent
            }});
        }
   });

iOS

NSData *byteData = [[NSData alloc] init];
[pushMessage postImageAsync:byteData andWithBlock:^(NSError *error) {
   // When the image is uploaded,
   // the push message must be
   // sent to the recipient.
   [pushMessage sendAsync:^(NSError *error) {
      // The Push message has been sent
   }];
}];

Swift

let data = NSData()
pushMessage.postImage(data) { (error) in
	if let error = error  {
		//do error handling here
	}
	pushMessage.send() { (error) in
	if let error = error {
		//do error handling here
	}
}

JavaScript

var sendCB = {
    onOk : function() {
         console.log("The Push message has been sent");
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
 
//// Assuming you already got your image data in a byte array
var picturePostCB = {
    onOk : function() {
       pushMessage.send(sendCB);
       
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
 
pushMessage.postImage(byteArray,picturePostCB);

..or attach a file and send the message to the recipient:

Android

// Assuming you already got your file data in a byte array
pushMessage.postFileAsync(byteArray, new AOMEmptyCallback() {
   public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception) {
        // When the file is uploaded, the push message must be sent to the recipient.
        pushMessage.sendAsync(new AOMEmptyCallback() {
 
            @Override
            public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception) {
                // The Push message has been sent
            }});
        }
   });

iOS

[pushMessage postFileAsync:byteData andWithBlock:^(NSError *error) {
   [pushMessage sendAsync:^(NSError *error) {
      // The Push message has been sent
   }];
}];

Swift

let data = NSData()
pushMessage.postFile(data) { (error) in
	if let error = error  {
		//do error handling here
	}
	pushMessage.send() { (error) in
	if let error = error {
		//do error handling here
	}
}

JavaScript

var sendCB = {
    onOk : function() {
         console.log("The Push message has been sent");
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
//// Assuming you already got your image data in a byte array
var filePostCB = {
    onOk : function() {
         pushMessage.send(sendCB);
       
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
 
pushMessage.postFile(byteArray,filePostCB);
}

Silent Push

Apple provides the possibility to mark push notifications as silent, so the user won't be noticing that a push message was received at all, in this special case. To mark your notification as a silent one, you have to set the contentAvailable property to the value 1 as shown in the code examples below:

Objective-C

AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
[pushMessage setContentAvailable:1];

Swift

let pushMessage = PushMessage()
pushMessage.contentAvailable = 1

Badges

To badge your iOS app's icon with a number to indicate news, you can set the badge property accordingly:

Objective-C

AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
[pushMessage setBadge:1];

Swift

let pushMessage = PushMessage()
pushMessage.badge = 1

To remove a previously set badge, you have to set the value to -1. This value is converted internally to 0 as required by Apple's Push Notification Service.

An example where this feature is used, is available on GitHub.

Additionally, the following modules are enriched with push functionality:

WordPress

ApiOmat checks changes on the WordPress instance periodically. If new or modified data was found, a push message is sent to the Wordpress owner user notifying him to fetch the changes.

Chat

When a new message was posted, a push message is send to all attendees, triggering the message update of the conversation locally.

Messenger

When a new message was posted, a push message is send to the receiver, notifying him about a new message in his inbox.

My Modules

You can also send Push Messages from the Dashboard using the My Modules screen.

images/download/attachments/27722192/db3-my-modules-push-screen.PNG