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.

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

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

The FCM API key, obtained from Google:

images/download/attachments/61478462/serverkey.JPG

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

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) {
			// ...
		}
	}
});

iOS

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 saveAsyncWithBlock:^(NSError *error) {
}];

Swift

let pushMessage = 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
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"]);
// Alternatively use pushMessage.setQuery(...) to send the push message to all users filtered by the query
var saveCB = {
    onOk : function() {
        console.log("saved");
    },
    onError : function(error) {
        console.log("Some error occured: (" + error.statusCode + ")" + error.message);
    }
};
pushMessage.save(saveCB);

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

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

iOS

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

let pushMessage = 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

JavaScript

var pushMessage = new Apiomat.PushMessage();
pushMessage.setPayload("Write your message here");
pushMessage.setReceiverUserName(["nameOfRecipient"]);
// Alternatively use pushMessage.setQuery(...) to send the push message to all users filtered by the query

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

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

TypeScript

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

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

TypeScript

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

Silent Push

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:

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.

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

@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

@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/61479719/db3-my-modules-push-screen.PNG