search

freshworks / hotline-phonegap

Hotline Phonegap Plugin
https://hotline.io
Other
6 stars 11 forks source link

readme

Hotline Phonegap plugin

Twitter

This plugin integrates Hotline's SDK into a Phonegap/Cordova project.

You can reach us anytime at contactus@hotline.io if you run into trouble.

AppId and AppKey You'll need these keys while integrating Hotline SDK with your app. you can get the same from the Settings -> API&SDK page. Do not share them with anyone. If you do not have an account, you can get started for free at hotline.io

Where to find AppId and AppKey

For platform specific details please refer to the Documentation

Supported platforms :

Note : This is an early version and so expect changes to the API

Integrating the Plugin :

  1. Add required platforms to your PhoneGap project

    cordova platform add android
cordova platform add ios

  2. Add the hotline plugin to your project.

You can add the plugin from command line like:

cordova plugin add hotline

You can also add it to your config.xml like 

<plugin name="hotline" source="npm"/>

Initializing the plugin

Hotline.init needs to be called from ondeviceready event listener to make sure the SDK is initialized before use.

document.addEventListener("deviceready", function(){
  // Initialize Hotline with your AppId & AppKey from your portal https://web.hotline.io/settings/apisdk
  window.Hotline.init({
    appId       : "<Your App Id>",
    appKey      : "<Your App Key>"
  });
});

The following optional boolean parameters can be passed to the init Object

//After initializing Hotline
showSupportChat = function() {
  window.Hotline.showConversations();
};
document.getElementById("launch_conversations").onclick = showSupportChat;

//in index.html
//<button id="launch_conversations"> Inbox </button>

Hotline APIs

In the above example clicking on show conversations in the filtered category list view takes you to a conversation view filtered by the tag "test".

You can pass in an optional callback function to an API as the last parameter, which gets called when native API is completed. Eg.

window.Hotline.unreadCount(function(success,val) {
    //success indicates whether the API call was successful
    //val contains the no of unread messages
});

Push Notifications

1. Recommended Option

To setup push notifications we recommend using our forked version of the phonegap-plugin-push available [here] (https://github.com/freshdesk/phonegap-plugin-push) .

It can be installed by the following command : 

cordova plugin add https://github.com/freshdesk/phonegap-plugin-push.git

Or you can add it to your config.xml like:

<plugin name="phonegap-plugin-push" spec="https://github.com/freshdesk/phonegap-plugin-push.git">
    <param name="SENDER_ID" value="XXXXXXXXXX" />
</plugin>

Initialize the push plugin and it will handle registering the tokens and displaying the notifications. here is a sample init function, call this in your onDeviceReady

function initializePush() {
    var push = PushNotification.init({
        "android":{
            "senderID":"XXXXXXXXXX"
        },
        "ios": {
            "alert": "true",
            "badge": "true",
            "sound": "true"
        },
        "windows": {}
    });
}
2. Alternate Option for Push

Follow the steps below if your app handles push notifications using any other plugin.

2a. Pass device token to Hotline

When you receive a deviceToken from GCM or APNS , you need to send the deviceToken to hotline as follows API name has changed for passing the token since version 1.2.0.

Version Method name
1.2.0 and later updatePushNotificationToken
less than 1.2.0 updateRegistrationToken 
// Example illustrates usage for phonegap-push-plugin
push.on('registration',function(data) {
  window.Hotline.updatePushNotificationToken(data.registrationId);
});
2b. Pass the notification to Hotline SDK

Whenever the app receives a push notification, check and pass the notification to Hotline SDK 

// Example illustrates usage for phonegap-push-plugin
push.on('notification', function(data) {
  window.Hotline.isHotlinePushNotification(data.additionalData, function(success, isHotlineNotif) {
    if( success && isHotlineNotif ) {
      window.Hotline.handlePushNotification(data.additionalData);
    }
  });
});
Push Notification Customizations

Android notifications can be customized with the updateAndroidNotificationProperties API. Following is a list of properties that can be customized.

The API can be invoked as below:

window.Hotline.updateAndroidNotificationProperties({
                "smallIcon" : "image",
                "largeIcon" : "image",
                "notificationPriority" : window.Hotline.NotificationPriority.PRIORITY_MAX,
                "notificationSoundEnabled" : false,
                "deepLinkTargetOnNotificationClick" : true
                "launchActivityOnFinish" : "MainActivity.class.getName()"
            });

Options for notificationPriority are as below:

This follow the same priority order as Android's NotificaitonCompat class.

DEPRECATED!

If you have been using the registerPushNotification call up until now, we recommend you use the method suggested above as we are removing support for it

window.Hotline.registerPushNotification('ANDROID_SENDER_ID'); // takes care of registration and handling of push notification on iOS and Android.

Caveats

Android :
iOS