. . .

Push Module Intro

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


The Push Module provides your app with the ability to send push messages to Android and iOS devices. Besides the ability 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.


Key Capabilities

Apple and Android

Send push notifications via FCM or APNS.

Media Push

Send media files, HTML notifications with badge support and decide whether to send silent notificiations.

Upload Certificates

Upload your certificate for each app.

Send to and from Clients

Send push notifications with logic integrated with the ApiOmat Dashboard, native Modules and the SDKs.

Module Setup & Configuration

FCM API Key (Android)

The FCM API key, obtained from Google:

images/download/attachments/61478462/serverkey.JPG

APNS certificate password (iOS)

Password for your APNS certficate.

Please note that passwordless APNS certificates are not supported.

APNS certificate (iOS)

The p12 encrypted APNS certificate is obtained from Apple

You can find a tutorial for getting an APNS certificate and a password here.

APNS default topic (iOS)

"You can use your APNs certificate to send notifications to your primary app, as identified by its bundle ID, as well as to any Apple Watch complications or backgrounded VoIP services associated with that app."

multiple topics in certificate
Extension ( 1.2.840.113635.100.6.3.6 )
Critical NO
Data com.yourcompany.yourexampleapp
Data app
Data com.yourcompany.yourexampleapp.voip
Data voip
Data com.yourcompany.yourexampleapp.complication
Data complication

(source: Communication with APNs)

If the used certificate includes multiple topics, the remote notification needs to include, which topic it is addressed to. You typically want to set the bundle ID of your app as the APNs default topic.


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 FCM: HTTPS

Combining APNS and FCM proxy configurations

You can only enter one proxy in the module configuration, but when you want to configure different proxys for APNS and FCM (for example a Socks Proxy for APNS and a HTTPS proxy for FCM), 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 you don’t know where to get the tokens.

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

Frontend Usage

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

Android

Android
PushMessage pushMessage = new PushMessage();
pushMessage.setPayload("A message from me");
pushMessage.setReceiverUserNames( Arrays.asList(new String[] {"testUser"}));
// Alternatively use pushMessage.setQuery(...) to send the push message to all users filtered by the query
pushMessage.saveAsync(new AOMEmptyCallback() {
@Override
public void isDone(boolean wasLoadedFromStorage, ApiomatRequestException exception) {
if (exception != null) {
// ...
}
}
});

Objective-C

Objective-C
AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
NSMutableArray *receivers = [[NSMutableArray alloc] init];
[receivers addObject:@"testuser"];
[pushMessage setPayload:@"A message from me"];
[pushMessage setReceiverUserNames:receivers];
// Alternatively use setQuery to send the push message to all users filtered by the query
[pushMessage saveObjCWithLoadAfterwards:true completion:^(NSError * error) {
}];

Swift

Swift
let pushMessage = AOMPushMessage()
pushMessage.payload = "A message from me"
pushMessage.receiverUserNames = ["testUser"]
// Alternatively use pushMessage.query = ... to send the push message to all users filtered by the query
pushMessage.save(loadAfterwards: true) { (error) in
if let error = error {
//do error handling here
}
}

TypeScript

TypeScript
const pushMessage = new PushMessage();
pushMessage.payload = "A message from me";
pushMessage.receiverUserNames = ["testuser"];
// Alternatively use pushMessage.query = ... to send the push message to all users filtered by the query
await pushMessage.save();

Media Push

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

Android

Android
PushMessage pushMessage = new PushMessage();
pushMessage.setPayload("Write your message here");
pushMessage.setReceiverUserNames( Arrays.asList(new String[] {"testUser"}));
// Alternatively use pushMessage.setQuery(...) to send the push message to all users filtered by the query

Objective-C

Objective-C
AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
NSMutableArray *receivers = [[NSMutableArray alloc] init];
[receivers addObject:@"testuser"];
[pushMessage setPayload:@"A message from me"];
[pushMessage setReceiverUserNames:receivers];
// Alternatively use setQuery to send the push message to all users filtered by the query

Swift

Swift
let pushMessage = AOMPushMessage()
pushMessage.payload = "A message from me"
pushMessage.receiverUserNames = ["testUser"]
// Alternatively use pushMessage.query = ... to send the push message to all users filtered by the query

TypeScript

TypeScript
const pushMessage = new PushMessage();
pushMessage.payload = "Write your message here";
pushMessage.receiverUserNames = ["nameOfRecipient"];
// Alternatively use pushMessage.query = ... to send the push message to all users filtered by the query

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

Android

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
}});
}
});

Objective-C

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

Swift

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
}
}

TypeScript

TypeScript
await pushMessage.postImage(imgByteArray);
await pushMessage.send();

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

Android

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
}});
}
});

Objective-C

Objective-C
[pushMessage postFileObjC:byteData completion:^(NSError * error) {
[pushMessage sendWithCompletion:^(NSError * error) {
// The Push message has been sent
}];
}];

Swift

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
}
}


TypeScript

TypeScript
await pushMessage.postFile(byteArray);
await pushMessage.send();

Silent Push (iOS)

Apple provides the possibility to mark push notifications as silent, so the user won't notice that they received a push message at all. 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:


Android

Android
PushMessage pushMessage = new PushMessage();
pushMessage.setContentAvailable(1);

Objective-C

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

Swift

Swift
let pushMessage = PushMessage()
pushMessage.contentAvailable = 1

TypeScript

TypeScript
const pushMessage = new PushMessage();
pushMessage.contentAvailable = 1;

Badges (iOS)

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


Android

Android
PushMessage pushMessage = new PushMessage();
pushMessage.setBadge(1);

Objective-C

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

Swift

Swift
let pushMessage = PushMessage()
pushMessage.badge = 1

TypeScript

TypeScript
const pushMessage = new 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.

APNS message topic (iOS)

The message topic typically is the bundle ID of the targeted app (or suffixed if Apple Watch complications or backgrounded VoIP services).


Android

Android
PushMessage pushMessage = new PushMessage();
pushMessage.setApnsTopic("com.yourcompany.yourexampleapp (or suffixed with .complications or .voip)");

Objective-C

Objective-C
AOMPushMessage *pushMessage = [[AOMPushMessage alloc]init];
[pushMessage setApnsTopic:@"com.yourcompany.yourexampleapp (or suffixed with .complications or .voip)"];

Swift

Swift
let pushMessage = PushMessage()
pushMessage.ApnsTopic = "com.yourcompany.yourexampleapp (or suffixed with .complications or .voip)"

TypeScript

TypeScript
const pushMessage = new PushMessage();
pushMessage.payload = "com.yourcompany.yourexampleapp (or suffixed with .complications or .voip)";

Native Module Usage

When your Native Module uses the Push module, you can send push messages as well.

To create this "uses" relation you can just add "Push" into the appropriate attribute of the @Module annotation in your module's main class, like this:Java

Java
@com.apiomat.nativemodule.Module( description="Some test module that uses the Push module", usedModules = { "Basics", "Push" }, securityPermissions = {} )
public class TestModule implements com.apiomat.nativemodule.IModule
{
...

After up- and downloading your module the Push module is included as a library and you can work with its classes.

If you didn't add the Push module to your app backend yet, you need to do this now, so you can configure it properly via the configuration dialogue in the Dashboard. See the section about the configuration at the beginning of this page for details.

Now you can do the following in one of your hook methods for example:Java

Java
@Override
public void afterPost( final com.apiomat.nativemodule.testmodule.TestClass obj,
final com.apiomat.nativemodule.Request r )
{
final PushMessage pm = ( PushMessage ) TestModule.AOM.createObject( r.getApplicationName( ),
PushMessage.MODULE_NAME, PushMessage.MODEL_NAME, r );
pm.setPayload( "You just created a TestClass object!" );
pm.setReceiverUserNames( Arrays.asList( r.getUserEmail( ) ) );
// Alternatively use pm.setQuery(...) to send the push message to all users filtered by the query
pm.save( );
}

The user who you want to send the push message to must have the "registration ID" / "device token" set so he can receive the push message.


Integrations

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.

Messaging

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

Dashboard Usage

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

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