Titanium - Legacy – xtremepush

With the XtremePush module for Titanium you can add XtremePush to both iOS and Android apps built with Titanium.

Platform Specific Information

XtremePush supports push notifications for iOS devices via Apples's Push Notification Service (APNs for short). And push notifications for Android devices via Google’s GCM (Google Cloud Messaging for Android) service. This page contains Titanium specific instructions but It is also recommended you read the native documentation for these platforms.

iOS
Android

This includes information on importing the SDKs, initialising the core integration and obtaining and uploading iOS and Android credentials for Push Notifications to the platform.

Advanced features include: tagging of events, custom push notification handling and location services can also be found in the SDKs section.

XtremePush Titanium SDK Setup

First, download the current Titanium module here. This zip file contains the module.

Next you must add the XtremePush Titanium module to your Titanium installation on your development machine if you have not already done so.

Mac OS X

If you are using Mac OS X copy the modules folder from the distribution zip file into the ~/Library/Application Support/Titanium folder and allow it to merge

Windows

If you are running Windows copy the modules folder from the distribution zip file into the C:\ProgramData\Titanium folder allow it to merge

Linux

If working on the Linux copy the modules folder from the distribution zip file into the ~/.titanium folder allow it to merge

Add Xtremepush to your Project in TitaniumStudio

When you have added the modules to your Titanium SDK installation you can use XtremePush in your project.

Modify the tiapp.xml

Import the XtremePush module into your project by double clicking your projects tiapp.xml in TitaniumStudio. You can add the module via the TiApp editor UI by clicking the green add button next to the list of modules,

XtremePush User Account Home

and selecting XtremPush from the drop down list

XtremePush User Account Home

you will see XtremePush in the list of modules if you have successfully added it.

XtremePush User Account Home

You can also add the module by editing tiapp.xml via the raw xml editor

<modules>
...
<module platform="android">com.xtremepush.xtremepush</module>
<module platform="iphone">com.xtremepush.xtremepush</module>
</modules>

For iOS you must make the following edits to tiapp.xml. Add the XtremePush app key and set the XtremePush sandbox mode to false

<ios>
<plist>
<dict>
<!-- remote notifications (ios) -->
<key>XtremePushApplicationKey</key>
<string>XTREME_PUSH_APP_KEY</string>
<key>XtremePushSandoxMode</key>
<false/>
<!-- remote notifications (ios) -->
</dict>
</plist>
</ios>

For details on how to connect your iOS app to the xtremepush platform and where to get the XTREME_PUSH_APP_KEY consult the iOS docs here.

If you are adding adding location services make sure to include NSLocationAlwaysUsageDescription to the plist, in iOS 8.0 and later this is required to Specify the reason for accessing the user’s location information.

<ios>
<plist>
<dict>
...
<key>NSLocationAlwaysUsageDescription</key>
<string>YOUR APPS reason for using location e.g. We use your 
location to find nearby parking spaces. </string>
</dict>
</plist>
</ios>

For Android you must make the following edits to tiapp.xml. Add the XtremePush app key and your google project number

<!-- remote notifications (android) -->
<property name="XtremePushApplicationKey" type="string">XTREME_PUSH_APP_KEY</property>
<property name="GoogleProjectNumber" type="string">GOOGLE_PROJECT_NUMBER</property>
<!-- remote notifications (android) -->

For details on how to connect your Android app to the xtremepush platform and where to get the XTREME_PUSH_APP_KEY and your GOOGLE_PROJECT_NUMBER consult the Android docs here.

You must also add the following android services, receivers and activities under the application tag as required:

Note

Replace any reference to YOUR_PACKAGE_NAME with the package name of your application. Entries that need further modification will have a comment “MODIFICATION NEEDED”

<android xmlns:android="http://schemas.android.com/apk/res/android">
<manifest>
...
<application>
...
<!-- REQUIRED FOR PUSH NOTIFICATIONS--> 
<activity
android:name="ie.imobile.extremepush.ui.DisplayPushActivity"
android:label="Push received"
android:theme="@android:style/Theme.Dialog"
android:exported="false" />

<service android:name="ie.imobile.extremepush.GCMIntentService" />

<receiver
android:name="ie.imobile.extremepush.receivers.GCMReceiver"
android:permission="com.google.android.c2dm.permission.SEND" >
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE" />
<action android:name="com.google.android.c2dm.intent.REGISTRATION" />
<!-- MODIFICATION NEEDED - Replace YOUR_PACKAGE_NAME with your package name --> 
<category android:name="YOUR_PACKAGE_NAME" />
</intent-filter>
</receiver>

<receiver
android:name="ie.imobile.extremepush.receivers.ReferrerReceiver">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
<!-- MODIFICATION NEEDED - Replace YOUR_PACKAGE_NAME with your package name --> 
<category android:name="YOUR_PACKAGE_NAME" />
</intent-filter>
</receiver>

<meta-data android:name="com.google.android.gms.version" android:value="7571000" />

<activity
android:name="ie.imobile.extremepush.ui.WebViewActivity"
android:exported="false" />

<!-- REQUIRED FOR LOCATION SERVICES-->
<service
android:name="ie.imobile.extremepush.location.ProxymityAlertReceiver"/>

<activity
android:name="ie.imobile.extremepush.ui.LocationDialogActivity"
android:label="Locations are not available"
android:theme="@android:style/Theme.Dialog"
android:exported="false" />

<!-- REQUIRED FOR IBEACON --> 
<service android:name="ie.imobile.extremepush.BeaconLocationService" />

<service android:enabled="true"
android:exported="true"
android:isolatedProcess="false"
android:label="iBeacon"
android:name="com.radiusnetworks.ibeacon.service.IBeaconService">
</service>

<!-- MODIFICATION NEEDED - Replace YOUR_PACKAGE_NAME with your package name --> 
<service android:enabled="true"
android:name="com.radiusnetworks.ibeacon.IBeaconIntentProcessor">
<meta-data android:name="background" android:value="true" />
<intent-filter
android:priority="1" >
<action android:name="YOUR_PACKAGE_NAME.DID_RANGING" />
<action android:name="YOUR_PACKAGE_NAME.DID_MONITORING" />
</intent-filter>
</service>

<application> 
</manifest>
</android>

And add the following android permissions as required:

<android xmlns:android="http://schemas.android.com/apk/res/android">
<manifest>
... 
<!-- REQUIRED for XtremePush -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<!-- Keeps the processor from sleeping when a message is received. -->
<uses-permission android:name="android.permission.WAKE_LOCK" />

<!-- REQUIRED PERMISSIONS for GCM (Push Notifications) -->
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<!-- GCM requires a Google account. -->
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<!-- This app has permission to register with GCM and receive message -->
<!-- MODIFICATION NEEDED - Replace YOUR_PACKAGE_NAME with your package name -->
<permission android:name="YOUR_PACKAGE_NAME.permission.C2D_MESSAGE" android:protectionLevel="signature" />
<uses-permission android:name="YOUR_PACKAGE_NAME.permission.C2D_MESSAGE" />
<!-- The two elements above ensure that only this application can receive the messages and registration result -->

<!-- OPTIONAL XtremePush settings-->
<!-- REQUIRED FOR GEO-LOCATION-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- REQUIRED FOR IBEACON -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<!-- REQUIRED IF you support iBeacon and your app must support devices that don't support BLE -->
<uses-feature 
android:name="android.hardware.bluetooth_le"
android:required="false" />

<application>
...
</application>

</manifest>
</android>

Enable XtremePush Mobile Analytics and Notifications in Classic Application

In your app.js or equivalent file; call Ti.Network.registerForPushNotifications and initialise a variable for xtremepush:

// Declare XtremePush
Ti.Network.registerForPushNotifications; // required to include Titanium AppDelegate code
var xtremepush = require("com.xtremepush.xtremepush");

Add the following code to your app.js to initialise XtremePush:

// Initialise XtremePush
xtremepush.registerForRemoteNotifications({
success : onRegister,
error : onRegistrationError, // only iOS
callback : onReceive,

// iOS specific; no effect for Android
types : [Ti.Network.NOTIFICATION_TYPE_ALERT, Ti.Network.NOTIFICATION_TYPE_BADGE, Ti.Network.NOTIFICATION_TYPE_SOUND],
});

Add the following callback functions to your app.js file:

// Initialise XtremePush
xtremepush.registerForRemoteNotifications({
success : onRegister,
error : onRegistrationError, // only iOS
callback : onReceive,

// iOS specific; no effect for Android
types : [Ti.Network.NOTIFICATION_TYPE_ALERT, Ti.Network.NOTIFICATION_TYPE_BADGE, Ti.Network.NOTIFICATION_TYPE_SOUND],
});

Here is an example of a simple app.js with the necessary XtremePush additions:

// This is a single context, single window application
// There is only one master window to which sub views will be added

//XtremePush Callback Functions
var onRegister = function(e) {
var success = e.success;
// always true
var errorCode = e.code;
// always 0
var deviceToken = e.deviceToken;

Ti.API.debug("Successfully registered with deviceToken " + deviceToken);
};

var onRegistrationError = function(e) {
var success = e.success;
// always false
var errorCode = e.code;
var error = e.error;
// localized error message

Ti.API.debug("Registration error: " + errorCode + " - " + error);
};

var onReceive = function(e) {
var inBackground = e.inBackground;
var notification = e.data;

// Check if message was recieved in Background or Foreground
if (inBackground) {

Ti.API.info("Received new notification inBackground=" + ": " 
+ notification.alert + " " + notification.special);

} else {

Ti.API.info("Received new notification inForeground=" + ": " 
+ notification.alert + " " + notification.special);

}

};

// Declare XtremePush
Ti.Network.registerForPushNotifications; // required to include Titanium AppDelegate code
var xtremepush = require("com.xtremepush.xtremepush");

(function() {
if (Ti.version < 1.8) {
alert('Sorry - this application requires Titanium Mobile SDK 1.8 or later');
} else {

var ApplicationWindow = require('ui/ApplicationWindow').ApplicationWindow;
new ApplicationWindow().open();
}

// Initialise XtremePush
xtremepush.registerForRemoteNotifications({
success : onRegister,
error : onRegistrationError, // only iOS
callback : onReceive,

// iOS specific; no effect for Android
types : [Ti.Network.NOTIFICATION_TYPE_ALERT, Ti.Network.NOTIFICATION_TYPE_BADGE, Ti.Network.NOTIFICATION_TYPE_SOUND],
});

})();

Enable in Alloy Application

If you are using Alloy, then you would add the following to your alloy.js file:

// Declare XtremePush
Alloy.Globals.xtremepush = require("com.xtremepush.xtremepush");

In your controller JavaScript file (index.js) you would then need to register the app with the XtremePush servers as follows:

Alloy.Globals.xtremepush.registerForRemoteNotifications({
success : onRegister,
error : onRegistrationError, // only iOS
callback : onReceive,
attributionsEnabled: true,

// Optional parameter to set the icon used in the push notification on Android.
// If set, the program will attempt to find and use iconfilenamewithoutextension.png
// in the *platform/android/res/drawable* folder in any notifications and will also
// search for a color entry with the same name in any of the XML files in the 
// *platform/android/res/values* folder to use as a background colour behind the icon. 
// setIcon : "iconfilenamewithoutextension",

// iOS specific; no effect for Android
types : [Ti.Network.NOTIFICATION_TYPE_ALERT, Ti.Network.NOTIFICATION_TYPE_BADGE, Ti.Network.NOTIFICATION_TYPE_SOUND],
});

Because of Titanium's new handling of Windows and TabGroups as activities in Android, there are a number of additional options which can be set in your index.js file. Here is a full sample index.js. $.index is the app's main TabGroup and $.b1-5 are example buttons which show some of the options available in the module.

 //XtremePush Callback Functions
var onRegister = function(e) {
var success = e.success;
// always true
var errorCode = e.code;
// always 0
var deviceToken = e.deviceToken;

Ti.API.debug("app.js_onRegister - Successfully registered with deviceToken " + deviceToken);
};

var onRegistrationError = function(e) {
var success = e.success;
// always false
var errorCode = e.code;
var error = e.error;
// localized error message

Ti.API.debug("app.js_onRegistrationError - Registration error: " + errorCode + " - " + error);
};

var onReceive = function(e) {
var inBackground = e.inBackground;
var notification = e.data;
Ti.API.debug("Push received while Activity is running: " + notification);

// Call push handler function with data from message
handlePush(notification.alert);
};

var onActivityOpen = function(e) {
switch(Ti.Platform.name) {
case 'android':
Ti.API.debug("onActivityOpen called");
var activity = Ti.Android.currentActivity;
var intent = activity.intent;

// This executes when a received push message notification from XtremePush is opened
if (intent.hasExtra("ie.imobile.extremepush.GCMIntenService.extras_push_message")) {
var notification = JSON.stringify(eval("(" + intent.getStringExtra("ie.imobile.extremepush.GCMIntenService.extras_push_message") + ")"));
notification = JSON.parse(notification);
if (Alloy.Globals.xtremepush.checkLastNotificationPush(notification['pushActionId'])){
Ti.API.debug("Push notification opened: " + notification);
Alloy.Globals.xtremepush.markPushAsRead(notification['pushActionId']);
// Call push handler function with data from message
handlePush(notification['alert']);
}
}
break;
}
};

var handlePush = function(exampleDataForProcessing) {
// Handle received push data
alert(exampleDataForProcessing);
};

var handlePushList = function(data) {
// Handle received push data
var pushArray = data.notifications;
for (var i=0; i < pushArray.length; i++)
{
Ti.API.debug(pushArray[i].pushActionId);
handlePush(pushArray[i].alert);
}
};

$.b1.addEventListener('click', function(e) {
Titanium.API.debug("You clicked the hit tag button");
Alloy.Globals.xtremepush.hitTag("ExampleTag");
});

$.b2.addEventListener('click', function(e) {
Titanium.API.debug("You clicked the hit impression button");
Alloy.Globals.xtremepush.hitImpression("ExampleImpression");
});

$.b3.addEventListener('click', function(e) {
Titanium.API.debug("You clicked the release all button");
Alloy.Globals.xtremepush.sendTags();
Alloy.Globals.xtremepush.sendImpressions();
});

batching = false;
$.b4.addEventListener('click', function(e) {
Titanium.API.debug("You clicked the toggle batching button");
batching = !batching;
Ti.API.debug(batching);
Alloy.Globals.xtremepush.setTagsBatchingEnabled(batching);
Alloy.Globals.xtremepush.setImpressionsBatchingEnabled(batching);
});

$.b5.addEventListener('click', function(e) {
Titanium.API.debug("You clicked the getPushList button");
Alloy.Globals.xtremepush.getPushNotifications({
success: handlePushList,
offset: 0,
limit: 1,
read: 0
});
});

// Declare XtremePush in alloy.js as shown here:
// Alloy.Globals.xtremepush = require("com.xtremepush.xtremepush");

var myProxy = Alloy.Globals.xtremepush.createLifecycle({lifecycleContainer: $.index});

// Add listener to TabGroup to catch app opens from a notification
$.index.addEventListener('open',onActivityOpen);
$.index.open();

Ti.API.debug("app.js - registering pushconnector");
// Initialise XtremePush
Alloy.Globals.xtremepush.registerForRemoteNotifications({
success : onRegister,
error : onRegistrationError, // only iOS
callback : onReceive,
attributionsEnabled: true,

// Optional parameter to set the icon used in the push notification on Android.
// If set, the program will attempt to find and use iconfilenamewithoutextension.png
// in the *platform/android/res/drawable* folder in any notifications and will also
// search for a color entry with the same name in any of the XML files in the 
// *platform/android/res/values* folder to use as a background colour behind the icon. 
// setIcon : "iconfilenamewithoutextension",

// iOS specific; no effect for Android
types : [Ti.Network.NOTIFICATION_TYPE_ALERT, Ti.Network.NOTIFICATION_TYPE_BADGE, Ti.Network.NOTIFICATION_TYPE_SOUND],
});

Build your app for iOS or Android and then send your first push using the appropriate instructions:

Sending your first push notification
- iOS
- Android

Retrieving your XtremePush ID

Now that your app is configured for mobile analytics and sending push notifications the final basic feature of XtremePush is retrieving your XtremePush ID. This can be accomplished by calling the deviceInfo method:

xtremepush.deviceInfo

This method returns your device's id as obtained from XtremePush server. If your device has not received an id then it has not successfully registered and there is an issue with your integration. If for example you want to quickly output the the device id to the debug area in TitaniumStudio you would use it like this:

Ti.API.debug("deviceInfo" + xtremepush.deviceInfo);

If you successfully retrieve the ID it can be used to identify your device on the platform and to send a push notification to just that device.

Articles in this section

Titanium - Legacy

Platform Specific Information

XtremePush Titanium SDK Setup

Mac OS X

Windows

Linux

Add Xtremepush to your Project in TitaniumStudio

Modify the tiapp.xml

Enable XtremePush Mobile Analytics and Notifications in Classic Application

Enable in Alloy Application

Retrieving your XtremePush ID

Comments

Articles in this section

Platform Specific Information

XtremePush Titanium SDK Setup

Mac OS X

Windows

Linux

Add Xtremepush to your Project in TitaniumStudio

Modify the tiapp.xml

Enable XtremePush Mobile Analytics and Notifications in Classic Application

Enable in Alloy Application

Retrieving your XtremePush ID

Related articles