Tracking mobile app and sending push notification

Tracking mobile app

If you have a mobile app (in Google Play Store or in Apple App Store), you can track it by using MiniCRM and you can communicate with the users of your mobile app via push notifications even if they did not sign up and provide email address, phone number etc.

To do this you need the following:

  • Your mobile app
  • Integrating a MiniCRM module into your app that registers the most important events such as installing the app or using the main functions. This module will also receive the push notifications coming from MiniCRM Doing all of this will allow you to build up your mobile users’ profile, reach and activate your users.

Sending push notifications

What is a push notification?

A push notification is an instant message sent to users’ mobile device. It is shown to them in the message center of the device just like missed calls. You can send push notifications to Android, iPhone and Windows Phone.
You can only send push notifications IF the user has installed your app AND the app is connected to MiniCRM AND the device is capable of receiving and displaying push notifications. Moreover, an identifier of the user’s device (you want to send push notification to) has to exist in your MiniCRM system.

Take a look at Apple’s article on push notifications: https://support.apple.com/en-us/HT201925

PhoneGap - An introduction

What is PhoneGap? PhoneGap is a free and open source framework that allows you to create mobile apps using standardized web APIs for the platforms you care about. MiniCRM API supports the registration of events and you can list and display the content of the messages using PhoneGap.

To use it, you have to install the PhoneGap PushPlugin:
For PhoneGap 2.Xhttps://github.com/phonegap-build/PushPlugin
For PhoneGap 3.Xhttps://github.com/jdhiro/PushPlugin

In addition, you have to install the PhoneGap Device plugin. You can do it with the following command:

phonegap local plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git

Always include the classes in the described order:

<script type="text/javascript" src="js/minicrm.js"></script>
<script type="text/javascript" src="js/minicrm-events.js"></script>
<script type="text/javascript" src="js/minicrm-messages.js"></script>
<script type="text/javascript" src="js/example.js"></script>

PhoneGap - Initializing on iOS

MiniCRM class

This is the base class, it collects and stores the data that is necessary for the connection and provides the link to the server. It has one function to call: Init.

Init function

This function has six parameters and it’s main role is to initialize the class and set the correct parameters. It also registers a PushToken on the APNS server and stores it in the app. If the app did not have a PushToken, an event is sent to MiniCRM called Installed.

MiniCRM.Init(SystemId, CategoryId, OnPushReceived, SenderId, AppVersion, Server);
  • SystemId (required): System Id of MiniCRM
  • CategoryId (required): Id of the module in MiniCRM
  • OnPushReceived (required): The name of the function that manages push notifications
  • SenderId (not necessary): Only important when integrating with Android, send false value when integrating with iOS
  • AppVersion (optional): The version of the mobile app can be sent in this parameter
  • Server (optional): When passing ‘TEST’ the data will be sent to the test environment, every other cases the data will be sent to the live environment.

Example:

function EventAlert(Event) {
    if (Event.alert) {
        navigator.notification.alert(Event.alert);
    }
}

MiniCRM.Init(22305, 3, "EventAlert", false, '1.0', 'TEST');

PhoneGap - Initializing on Android

Google API

To send Google push notifications, a Google Project is needed with push notifications enabled.

For more information, see: https://developers.google.com/cloud-messaging/

MiniCRM class

This is the base class, it collects and stores the data that is necessary for the connection and provides the link to the server. It has one function to call: Init.

Init function

This function has six parameters and it’s main role is to initialize the class and set the correct parameters. It also registers a PushToken on the GCM server and stores it in the app. If the app did not have a PushToken, an event is sent to MiniCRM called Installed.

MiniCRM.Init(SystemId, CategoryId, OnPushReceived, SenderId, AppVersion, Server);
  • SystemId (required): System Id of MiniCRM
  • CategoryId (required): Id of the module in MiniCRM
  • OnPushReceived (required): The name of the function that manages push notifications
  • SenderId (required): The Project Number of the Google API
  • AppVersion (optional): The version of the mobile app can be sent in this parameter
  • Server (optional): When passing ‘TEST’ the data will be sent to the test environment, every other cases the data will be sent to the live environment.

Example:

function EventHandler(Event) {
    switch(Event.event) {
        // The event fires when the PushToken is registered
        case 'registered':
            if (Event.regid.length > 0) {
                // IMPORTANT: send the registered token to the client
                MiniCRM.SetToken(Event.regid);
            }
            break;

        case 'message':
            // The event fires when the application goes foreground
            if (Event.foreground) {
                console.log('--INLINE NOTIFICATION--');
            } else {
                // The app starts as the user clicked on the message
                if (Event.coldstart) {
                    console.log('--COLDSTART NOTIFICATION--');
                } else {
                    console.log('--BACKGROUND NOTIFICATION--');
                }
            }

            // The content of the message and the number of the messages
            console.log('MESSAGE -> MSG: ' + Event.payload.message + ' || MSGCNT: ' + Event.payload.count);
            break;

        case 'error':
            // There was an error during processing the push notifications
            console.log('ERROR -> MSG:' + Event.msg);
            break;

        default:
            // All other case
            console.log('EVENT -> Unknown, an event was received and we do not know what it is');
            break;
    }
}

MiniCRM.Init(22305, 3, "EventHandler", "670330094152", '1.0', 'TEST');

PhoneGap - Shared services

MiniCRM.Events class

This class is responsible for adding events to MiniCRM such as first login, opening the app or others.

The class contains two functions, Post and PostContact.

Post function

This class is responsible for adding events to MiniCRM such as first login, opening the app or others.

The class contains two functions, Post and PostContact.

MiniCRM.Events.Post(Name, Data, CallBack);
  • Name (required): Name of the event
  • Data (optional): Additional data related to the event. Has to be an array and the following indexes are processed: Category1, Category2, Value1, Value2. Category is a string that contains the event category, value is an int that contains the event value.
  • CallBack (optional): Name of the function called after successful run. The function gets the standard Ajax response parameters (data, textStatus, jqXHR)

Example:

function SampleCallBack(r, s, x) {
    console.log('Response: ' + r);
}

Data = { };
Data['Category1'] = 'Cars';
Data['Category2'] = 'Houses';
Data['Value1'] = 4;
Data['Value2'] = 1;

MiniCRM.Events.Post('AdSent', Data, SampleCallBack);

PostContact function

The function registers the user data into MiniCRM. It has five parameters.

This data can be registered once per device.

MiniCRM.Events.PostContact(EventName, Email, FirstName, LastName, CallBack);
  • EventName (required): Name of the event
  • Email (required): Email address of the user
  • FirstName (required): First name of the user
  • LastName (required): Last name of the user
  • CallBack (optional): Name of the function called after successful run. The function gets the standard Ajax response parameters (data, textStatus, jqXHR)

Example:

function SampleCallBack(r, s, x) {
    console.log('Response: '+ r);
}

MiniCRM.Events.PostContact('LoggedIn', 'example@mc.local', 'John', 'Smith', SampleCallBack);

MiniCRM.Messages class

This function could generate a list of the messages belonging to the devices as well as the content of the messages. It contains three functions: List, Get and Delete.

List function

The function generates the list of the push notifications belonging to the device. It has two parameters.

MiniCRM.Messages.List(SuccessCallBack, ErrorCallBack);
  • SuccessCallBack (required): Name of the function called after successful run. The function gets the standard Ajax response parameters (data, textStatus, jqXHR)
  • ErrorCallBack (optional): Name of the function called after unsuccessful run. The function gets the standard Ajax error parameters (data, textStatus, errorThrown)

Example:

function SampleSuccess(r, s, x) {
    console.log('Message count: ' + r.Count);

    $.each(r.Messages, function(index, value) {
        // Message Id
        console.log('Message Id: ' + value.Id);

        // Message subject
        console.log('Message Subject: ' + value.Subject);

        // Date of first open
        console.log('Message OpenedAt: ' + value.OpenedAt);

        // Creation date of the message (date when message sent)
        console.log('Message CreatedAt: ' + value.CreatedAt);

        // Message template (if the message was a template)
        console.log('Message Name: ' + value.Name);

        // Template folder of the message (if the message was a template)
        console.log('Message Folder: ' + value.Folder);
    }
}

function SampleError(x, s, e) {
    console.log('There was an error: ' + s);
}

MiniCRM.Messages.List(SuccessCallBack, ErrorCallBack);

Get function

Returns with the content of a message. It has three parameters.

MiniCRM.Messages.Get(Id, SuccessCallBack, ErrorCallBack);
  • Id (required): Message ID
  • SuccessCallBack (required): Name of the function called after successful run. The function gets the standard Ajax response parameters (data, textStatus, jqXHR)
  • ErrorCallBack (optional): Name of the function called after unsuccessful run. The function gets the standard Ajax error parameters (data, textStatus, errorThrown)

Example:

function SampleSuccess(r, s, x) {
    // Subject of the message
    console.log('Message Subject: ' + r.Subject);

    // Message template (if the message was a template)
    console.log('Message Name: ' + r.Name);

    // Template folder of the message (if the message was a template)
    console.log('Message Folder: ' + r.Folder);

    // Content of the message
    console.log('Message Content: ' + r.Content);

    // If the message was deleted or not
    console.log('Message Deleted: ' + r.Deleted);
}

function SampleError(x, s, e) {
    console.log('There was an error: ' + s);
}

MiniCRM.Messages.Get(8, SampleSuccess, SampleError);

Delete function

Deletes a push notification from the list. It has two parameters.

MiniCRM.Messages.Delete(Id, CallBack);
  • Id (required): Message ID
  • CallBack (optional): Name of the function called after successful run. The function gets the standard Ajax response parameters (data, textStatus, jqXHR)

Example:

function SampleCallBack(r, s, x) {
    if(r.Status == "Ok") console.log('Delete successful!');
}

MiniCRM.Messages.Delete(8, SampleCallBack);

REST API (for native apps)

When developing a native app, the API can be used with http GET and POST request. The following functions are available:

Registering events

This function is responsible for registering events into MiniCRM such as first login, opening the app or others. The events can be sent with POST request and four unique values can be passed with the names: Category1, Category2, Value1, Value2. Moreover, you can assign user data to unique identifiers: Firstname, Lastname and Email address.

User data can be assigned to one identifier only once. After that, the system will ignore other user data.

Url: https://r3.minicrm.hu/Api/Event/$SystemId
SystemId: System Id of MiniCRM

Parameters:

  • UUId (required): Unique identifier of the mobile device
  • CategoryId (required): Identifier of the mobile module in MiniCRM
  • PushToken (optional): The identifier generated by GCM/APNS API for sending push notifications
  • Name (required): Event name
  • Category1 (optional): Event category, string
  • Category2 (optional): Event category, string
  • Value1 (optional): Event value, int
  • Value2 (optional): Event value, int
  • Device (optional): Device type, ‘Android’, ‘iOS’ or ‘Wondows Phone’
  • Email (optional): User’s email address
  • FistName (optional): User’s first name
  • LastName (optional): User’s last name

Example:

$ curl -d "UUId=fd43ffdd1c78d54d&CategoryId=3&Name=NewEvent" https://r3.minicrm.hu/Api/Event/22305

Response:

"Event successfully saved!"

Downloading events (inbox)

It can download the list of non-deleted messages belonging to a device. It works with a GET request.

Url: https://r3.minicrm.hu/Api/Message?SystemId=$SystemId&UUId=$UUId

Parameters:

  • SystemId (required): System Id of MiniCRM
  • UUId (required): Unique identifier of the mobile device

Example:

$ curl https://r3.minicrm.hu/Api/Message?SystemId=22305&UUId=fd43ffdd1c78d54d

Response:

{
    "Count": 1,
    "Messages": {
        "8": {
            "Id": 8,
            "Subject": "This is the subject of the message",
            "OpenedAt": "0000-00-00 00:00:00",
            "CreatedAt": "2014-09-16 18:05:22",
            "Name": "Name of the template",
            "Folder": "Folder of the template"
        }
    }
}

Downloading message content

Downloading message content can be done with a GET request.

Url: https://r3.minicrm.hu/Api/Message/$MessageId?SystemId=$SystemId&UUId=$UUId

Parameters:

  • MessageId (required): Message Id
  • SystemId (required): System Id of MiniCRM
  • UUId (required): Unique identifier of the mobile device

Example:

$ curl https://r3.minicrm.hu/Api/Message/8?SystemId=22305&UUId=fd43ffdd1c78d54d

Response:

{
    "Subject": "This is the subject of the message",
    "Name": "Name of the template",
    "Folder": "Folder of the template",
    "Content": "Here appears the content of the message...",
    "Deleted": 0
}

Deleting message

Deleted messages will not appear in the downloaded message list but it can be found in MiniCRM. Can be called with a POST request.

Url: https://r3.minicrm.hu/Api/Message/$MessageId/Delete
MessageId: Message Id

Parameters:

  • SystemId (required): System Id MiniCRM
  • UUId (required): Unique identifier of the mobile device

Example:

$ curl -d "UUId=fd43ffdd1c78d54d&SystemId=22305" https://r3.minicrm.hu/Api/Message/8/Delete

Response:

{"Status":"Ok"}