In Convertigo 7.1 we introduce the new PushManager. This article explains how push are handled in Convertigo and how to build your mobile apps supporting push and how to configure the Server Part



 

Preparing the environment.

Here are for the supported Push Systems the push architectures:

iOS

iOS Push is based on Apple’s Push Notification services (APNS). To use APNS, you must have from Apple an ‘Apple Push Notification service SSL (Production)’ certificate attached to your paid iOS Developer Program account. You will need a APNS certificate. To create a APNS certificate, go to Apple’s developer portal : https://developer.apple.com/account/ios/certificate/certificateList.action

From there :

To create the certificate, you will need an App ID. Be sure this App ID is the same as Convertigo ‘Application Id’ property configured in the ‘Mobile_application’Object of your Convertigo project.

  • Create a new ‘APP ID’ of your application: ‘Identifiers >APP IDs’ section
  • Bundle ID = application ID, generally begins by ‘com.convertigo.mobile.’ for Convertigo
  • When your APP ID is created, create a new certificate: ‘Certificates’ section
  • Choose
    • If you do not have not a Mac Computer, you must use openSSL
    • Install openSSL and generate ‘.csr’ and ‘.key’ files
      • Download Open SSL from : http://www.openssl.org/related/binaries.html
      • Use these commands to create a certificate request :
        openssl genrsa -out ‹myfile›.key 2048
        openssl req -new -key ‹myfile›.key -out ‹myfile›.certSigningRequest -subj "/emailAddress=‹myemail›, CN=‹mycompany›, C=‹mycountry›"
        
    • Goto https://developer.apple.com/account/ios/certificate/certificateList.action,
    • Upload your csr file to produce your ‘.cer’ file
    • Download your ‘.cer’ file. For example: ‘aps_production.cer’
Now, you should have 3 files:
  • ‹myfile›.csr
  • ‹myfile›.key
  • aps_production.cer
All these files must be saved and be moved to ‘C:\OpenSSL-Win32\bin’ Apple Dev portal will enable you to download the certificate in the ‘.csr’ format, but Convertigo uses the ‘.P12’ format. Be sure to convert your APNS certificate to .P12. You can use the openssl tool to do that:
  • Use these commands to convert to .P12 : To generate a PEM file:
    openssl x509 -in aps_production.cer -inform DER -out aps_production.pem -outform PEM
    To generate a p12 file:
    openssl pkcs12 -export -inkey ‹myfile›.key -in aps_production.pem -out ‹myfile›.p12 -passout pass:‹mypassword›
You should end up with:
  • A .P12 Certificate file (A)
  • A password for this certificate (B)
These items will be used later on to configure Convertigo’s Push Notification step.

Android

Android push needs some configuration in the Google Api Console. You have to connect to your Google developer Console : https://console.developers.google.com/project From there :
  • Create a new project
  • Click on the project you created and see the project number. You will need it to configure Convertigo’s PushNotification Step.
  • On the left side of the page click on the ‘Api & Auth’ link then look for the ‘Google Cloud Messaging for Android’ button and turn it on.
  • On the left side click on the ‘API&Auth -> Credentials’. Then click on the ‘Public key Access ->New Key’ red button.
  • Choose a Server key and enter the IP addresses from where the Convertigo Server will generate the push requests.
  • Click Create and look for the ‘API key‘ generated by Google. You will need this key to configure Convertigo’s Push Notification Step.
You should have now :
  • A Project Number (C)
  • An Api Key (D)
 

Configuring the PushNotification Step on the Convertigo Server

Within a sequence at any time you can use the Push Notification Step. Be sure to configure the Step properties:

iOS Properties

  • APNS Certificate password : The certificate password (B)
  • APNS Certificate: The P12 Certificate file reference (A). You can use the Convertigo file reference syntax:
    • .//‹Path relative to the project root› or
    • ./‹Path relative to filesystem root› (Note: do not put the P12 certificate in the ‘DisplayObject’ folder as it will be packaged within the mobile app during the build process, breaching security)
  • APNS Notification type : Message, Badge , or Sound

Google Cloud messaging Properties:

  • Google API Key : The API key (D) (string: don’t forget double quotes)
Note: Of course you can use Convertigo global symbols in these properties to have your project independent from the environment.  

Using the lib_PushManager library project

This project is in the libraries projects wizard. In the studio, click new->project->Convertigo Projects->libraries->lib_PushManager. This project must be deployed on the target Convertigo Server. Its role is to handle push notification registrations from mobile devices. For that, the project holds a sequence named ‘RegisterDevice’ called by the Mobile devices and add automatically by c8o.device.cordova.js library. ‘RegisterDevice’ is provided two variables:
  • token (The token generated by the mobile device)
  • comment (A Comment field )
This project also uses a SQL Connector to register the devices tokens in the PushNotification database. You must configure the SQL connector properties to address the correct database:
  • Database URL
  • Driver
  • User Name
  • Password
These are standard SQL connector properties, you can find details here: http://help.convertigo.com/latest/topic/com.twinsoft.convertigo.studio.help/help/helpRefManual/SQLconnector.html Note: Again, you can use Convertigo global Symbols here. Be sure to have a database with the correct schema created. The lib_PushManager needs a table of this schema
Token comment
By default the table name is ‘push_demo’ you can customize that in the Transaction’s ‘Query’ property  

Configure your Mobile App

Once the server is configured, you can configure the client side mobile application. To use the push notification services, be sure this line is included :
‹script src="scripts/c8o.device.cordova.js" type="text/javascript"›‹/script›
In your project’s ‘DisplayObject/mobile/app.html’ file. As Convertigo handles cross-platform development with the same source code you just have to configure Push notifications in your app for all the target platforms. Also, be sure to uncomment the push plugin reference in the config.xml files for each of the target platforms.

Android Devices

For android support, you must configure in your client application the ‘Project Number (C). This is done in your ‘DisplayObject/mobile/js/custom.js file:
/** 
 * cordova read-only variables values can only be set directly here, not dynamically. Used by c8o.device.cordova.js 
 */ 
 cordova: { 
	androidSenderID: "‹project number›" 
 }, 

iOS devices

Nothing more has to be done for iOS devices.  

Sending a Push notification

At any time in your project’s sequences you can use the PushNotification Step to send notifications. The step uses ‘sourceables’ properties to send the notifications:
  • Devices Tokens: a list of tokens tagged as ‘deviceId’
  • Notification Data: the data to be sent in the push notification.
    • iOS: Depends on the message type (message, badge, or sound)
    • Android : Just the payload.
The general mechanism to send push notification is having your sequence to call access the PushNotification database by a SQL Connector, select the tokens, iterate on the rows and build a complex of this type
‹devices›
	‹deviceId›APNS:XXXXXXXXX‹/deviceId›
	‹deviceId›APNS:XXXXXXXXX‹/deviceId›
	‹deviceId›GCM:XXXXXXXXX‹/deviceId›
	‹deviceId›GCM:XXXXXXXXX‹/deviceId›
‹/devices›
Then source the ‘Device Token’ Property of the PushNotification step by the elements. The PushNotification step will iterate automatically through all devices ids and select the correct push system (Apple or Google) according the the device Id. In this way with one Step, you will notify all your devices. Source the ‘Notification data’ field to some data you want to send to the devices.  

Receiving Notifications in your Mobile App

If you want to handle the notification you receive you can add some code in your custom.js to handle the ‘push_notification’ hook.
 /** 
 *  push_notification hook 
 *  ** Needs cordova.js + c8o.cordova.js **
 *  Hook called when a notification is received on the mobile device  *
 *  sender: "string" sender of the notification : GCM (Google) or APN (Apple)
 *  msg: "string" the message content of the notification
 *  event: "object" the raw object from the notification, sender specific
 *  return: true > lets c8o.cordova handle the response (Apple badge or sound)
 *            false > do nothing
 */ 
C8O.addHook("push_notification", function (sender, msg, event) { 
	 // Do whatever has to be done here to handle the push notif.. 
	 return true;
});

You will receive the notification message in the msg variable. You are free to handle it the way you want. For example, you can use this message as a link to display some more data in your application.

1 comment

Leave a comment