search

techaffinity / freshchat-phonegap

Freshchat sdk for phonegap
7 stars 36 forks source link

readme

Freshchat Phonegap plugin

(https://twitter.com/freshchatapp)

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

You can reach us anytime at support@freshchat.com if you run into trouble.

AppId and AppKey You'll need these keys while integrating Freshchat 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 Freshchat.com

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 Freshchat plugin to your project.

You can add the plugin from command line like:

cordova plugin add https://github.com/techaffinity/freshchat-phonegap.git

To prevent build failures caused by including different versions of the support libraries in Android gradle. Add the below plugin

https://github.com/dpa99c/cordova-android-support-gradle-release

To resolve these version collisions, this plugin injects a Gradle configuration file into the native Android platform project, which overrides any versions specified by other plugins, and forces them to the version specified in its Gradle file.

Initializing the plugin

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

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

For Ionic 2 & 3 :

Access Freshchat variable in the development as below

((window as any).Freshchat) likewise

// Initialize Freshchat with your AppId & AppKey from your portal https://web.Freshchat.com/settings/apisdk (window as any).Freshchat.init({ appId : "", appKey : "" }); });

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

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

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

Freshchat 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.Freshchat.unreadCount(function(success,val) {
    //success indicates whether the API call was successful
    //val contains the no of unread messages
});

Eg.

    window.Freshchat.sendMessage(
        {tag:”premium”,message:”Helo..”},function(success){
        //success indicates whether the API call was successful
    });

UnRead Count

If you would like to obtain the number of unread messages for the user at app launch or any other specific event, use this function. Eg.

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

The plugin can also choose to listen to changes to unread count when the app is open. The way to listen to the broadcast is described below. To register : Eg.

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

To unregister : Eg.

window.Freshchat.unreadCountlistenerUnregister(function(success,val) {
    //success indicates whether the API call was successful
    //val contains the message for the success.
});

Restore user

For retaining the chat messages across devices/sessions/platforms, the mobile app needs to pass the same external id and restore id combination for the user. This will allow users to seamlessly pick up the conversation from any of the supported platforms - Android, iOS and Web.

External Id - This should (ideally) be an unique identifier for the user from your system like a user id or email id etc and is set using the Freshchat.identifyUser() API. This cannot be changed once set for the user

Restore Id - This is generated by Freshchat for the current user, given an external id was set and can be retrieved anytime using the Freshchat.getUser().getRestoreId() API. The app is responsible for storing and later present the combination of external id and restore id to the Freshchat SDK to continue the chat conversations across sessions on same device or across devices and platforms.

Note 1 : Restore Id for a user is typically generated only when user has sent a message.

Note 2 : Notifications are supported in only one mobile device at any point in time and is currently the last restored device or device with last updated push token

To set external id : Eg.


    window.Freshchat.identifyUser({externalId:"123456",restoreId:null},function(success){
       //success indicates whether the API call was successful
    });

To retrieve the restore id:

Eg.

Freshchat.getRestoreID(function(success,restoreId){
     //success indicates whether the API call was successful
     //restoreId contains the restoreId generated for user.
      console.log("value restore Id : "+ restoreId);
    });

To restore user :

Eg.

    window.Freshchat.identifyUser({externalId:"123456",restoreId:"ce85c2ba-cc2a-4ad2-8074-aa3b46cdc3c3"},function(success){
       //success indicates whether the API call was successful
    });

To lookup and restore user by external id and restore id:

To Register Eg.

   window.Freshchat.registerRestoreIdNotification(function(success,jsonOBJ){
       //success indicates whether the API call was successful
       //jsonOBJ contains the restoreId and externalId
      console.log("value  : "+ JSON.stringify(jsonOBJ));
  });

To Unregister

Eg.

   window.Freshchat.unregisterRestoreIdNotification(function(success){
       //success indicates whether the API call was successful
  });

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/techaffinity/phonegap-plugin-push) .

It can be installed by the following command : 

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

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

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

To Support Android FCM Push Notification and Cordova-android versions above 7.1.0, use the below plugin https://github.com/techaffinity/phonegap-plugin-push-1

Changes:

  1. Removed Depreciated GCM and moved to FCM for Android

It can be installed by the following command : 

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

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

<plugin name="phonegap-plugin-push" spec="https://github.com/techaffinity/phonegap-plugin-push-1">
    <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 Freshchat

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

// Example illustrates usage for phonegap-push-plugin
push.on('registration',function(data) {
  window.Freshchat.updatePushNotificationToken(data.registrationId);
});
2b. Pass the notification to Freshchat SDK

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

// Example illustrates usage for phonegap-push-plugin
push.on('notification', function(data) {
  window.Freshchat.isFreshchatPushNotification(data, function(success, isFreshchatNotif) {
    if( success && isFreshchatNotif ) {
      window.Freshchat.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.Freshchat.updateAndroidNotificationProperties({
                "smallIcon" : "image",
                "largeIcon" : "image",
                "notificationPriority" : window.Freshchat.NotificationPriority.PRIORITY_MAX,
                "notificationSoundEnabled" : false,
                "launchActivityOnFinish" : "MainActivity.class.getName()"
            });

Options for notificationPriority are as below:

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

Restore User

    window.Freshchat.identifyUser( {
        externalId: "USER_EXTERNAL_ID",
        restoreId: "USER_RESTORE_ID"
    });

Note: If user does not have restoreId, call identifyUser() with just externalId.

Caveats

Android :
iOS