Skip to content

Users and installations

Jump to bottom
Alexander Boldyrev edited this page Oct 28, 2024 · 7 revisions

Table of contents

Terminology

Mobile Messaging SDK employs specific terms in order to address different type of information that you can synchronize towards Infobip Platform. You will see User and Installation terms in the SDK similarly to what you can see at People section at Infobip Portal.

Seaching for user profile
  • Installation is a specific installation of your application. Each application installation on a device receives unique installation ID - pushRegistrationId. pushRegistrationId is a permanent ID assigned to the app once it’s launched up until the moment it’s uninstalled from the device. In this documentation, the terms 'installation' and 'push registration' are used interchangeably and denote the same concept. You can see it as Mobile App Messaging (Push Notifications) destination under Contact Information tab of a user profile. A single user can have zero or more installations of different applications. You can change some specific settings of each installation of a user, add Custom attributes to it or do a remote Logout of a specific installation.
  • User represents a single person profile with Standard attributes, Custom attributes and Tags which you can set via the SDK.

Both user and installation objects are initialized once Mobile Messaging SDK is successfully started.

Installation

Installation is a specific installation (or instance) of your application on a user's device. One user can have multiple installations. Standard attributes and their descriptions are available in docs, code - Installation. One user can have multiple installations.

You can get current installation details from server using function MobileMessaging.fetchInstallation(callback, errorCallback):

mobileMessaging.fetchInstallation(
    installation => {
        // Here you can use the installation object
    }
);

Moreover all current user installations are available under user profile.

var user = ...;

var installations = user.installations;

How to find a specific installation on Infobip Portal

Infobip creates an empty user profile as soon as device registers on the platform. Afterwards you should be able to find this user profile at Infobip Portal using for example pushRegistrationId (or other attributes, such as phone number, in case the installation was personalized) provided via the SDK: Searching for user profile

Enabling/disabling push installation

You can temporarily "disable" your installation if you don't want to receive push notifications:

mobileMessaging.getInstallation(installation => {
	installation.isPushRegistrationEnabled = false;
	mobileMessaging.saveInstallation(installation,
	    updatedInstallation => {
	        // Here you can use updated installation
	    }
	);
});

Setting installation as primary

On the Infobip account, a single user profile can have one or more mobile devices with the application installed. You might want to mark one of these devices as the primary device and send push messages only to this device (e.g. receive bank authorization codes only on one device). To achieve this and similar use-cases, you can utilize the APIs provided by the Mobile Messaging SDK.

For this feature to work, the API request for sending the push notification must include a special parameter targetOnlyPrimaryDevices set to true. Parameters for sending a single push notification can be checked in the Infobip API Docs. With this parameter, push notifications will not be sent to any installations that are not marked as primary. This means that for this feature to work, both the mobile implementation and the API request parameter must be used in conjunction.

By default, all installations are marked as non-primary. To set a particular installation as primary, either the Contact Information API or the following Mobile Messaging SDK API can be used:

mobileMessaging.getInstallation(installation => {
	installation.isPrimaryDevice = true;
	mobileMessaging.saveInstallation(installation,
	    updatedInstallation => {
	        // Here you can use updated installation
	    }
	);
});

You can set/reset primary setting for any other installation of a current user:

var pushRegId = '< Push Registration ID of another installation >';
mobileMessaging.setInstallationAsPrimary(
    pushRegId,
    true,
    () => {
        // Success callback
    }
);

Custom attributes

An Installation can have custom attributes the same way as User does, so that you would be able to reach only specific installation of a user.

mobileMessaging.getInstallation(installation => {
	installation.customAttributes = { OneTimePasswords: true };
	mobileMessaging.saveInstallation(installation,
	    updatedInstallation => {
	        // Here you can use updated installation
	    }
	);
});

These custom attributes can be seen under push destination on portal:

Custom attributes of an installation

User

You can provide additional user's data to the server, so that you will be able to send personalised targeted messages to exact user and have other nice features. Library supports a set of predefined attributes as well as custom ones.

You can always get current user data from server via the SDK API. The request produce an HTTP call, so make sure to handle failures if any.

mobileMessaging.fetchUser(
    user => {
        // Here you can use fetched user instance
    }
);

User types (roles)

There are two types of user profiles: Lead and Customer:

Leads

Leads are profiles with the person`s name and contact information that has not been verified.

Customers

Leads are changed to Customers during personalization using the provided identifiers. If profile is already a Customer, profile is updated with the information about the installation.

Personalization: external user ID, emails and phone numbers

Each user can have External user ID, Emails and Phone numbers. These fields are unique identifiers of a user profile on Infobip platform and provide capability to personalize any app installation with a user profile. The platform provides data grouping functions based on these parameters. For example, if two installations of a particular app will try to save the same External user ID, then both of them will be collected under a single user. Phone number, Email and External user ID are also widely used when targeting users with messages across different channels via Infobip platform.

Following restrictions apply:

It is also possible to set User attributes on personalization using UserAttributes. It will override any existing values, so use carefully.

var userIdentity = {
    externalUserId: "ExternalId", 
    // phones: ["38516419710"], 
    // emails: ["[email protected]"]
};

//replaces existing values set to the person with provided ones
var userAttributes = {
    firstName: "John",
    lastName: "Doe",
    gender: "Male",
    birthday: "1968-02-10",
    tags: ["Promotions", "Transactions"],
    customAttributes: {
        favoriteMeal: "pizza",
        bootSize: 9,
        installationDate: "2019-01-01",
        lastVisitDateTime: "2020-12-01T08:50:18Z",
        isSubscribed: true,
        height: null,
        favsList: [{
            id: "1",
            price: 99.99,
            sale: true
        },
            {
                id: "2",
                price: 149.99,
                sale: false
            }]
    }
};

mobileMessaging.personalize(
    {
        userIdentity: userIdentity,
        userAttributes: userAttributes,
        forceDepersonalize: <true/false>,
    }
        () => {
            // Here you can use updated user instance
            console.log('Success' + JSON.stringify(user));
          }, (error) => {
            console.log('Error' + JSON.stringify(error));
        }
);

External User ID

You can use External User ID to uniquely target your user. External User ID is meant to be an ID of a user in an external (non-Infobip) service. It can be any string and can be shared across different instances of your app, so that a user with multiple devices can still be targeted as a single user of your app. Notice: for externalUserId any string values such as "null", "Null" or "NULL" are not supported and would be considered as JSON null.

Depersonalization

You can depersonalize current installation to detach it from current user profile so that the user won't receive messages when targeted by any person attribute:

mobileMessaging.depersonalize(
    () => {
        // Success callback
    }
);

You also can depersonalize any installation that is personalized with the current user (perform remote logout).

var pushRegId = '< push reg id of another installation of user >';
mobileMessaging.depersonalizeInstallation(
    pushRegId,
    () => {
        // Success callback
    }
);

Q: When should I log out my users? A: Application users can (and probably should) be logged out if the app meets all the following conditions:

  • you leverage user attributes functionality
  • your application has "log out"/"sign out" feature
  • you don't want a newly logged in (signed up) user to be targeted by other user's data (such as phone numbers, first name, custom attributes etc.) and receive personalized messages
  • you want logged out (signed out) user to still receive broadcast notifications (if not, you need to disable push registration)

Personalize with force depersonalization

If you want previous personalization to be reset, in other words, depersonalize this particular installation, provide a special argument forceDepersonalize:

var userIdentity = {
    externalUserId: "ExternalId",
    // phones: ["38516419710"],
    // emails: ["[email protected]"],
};

mobileMessaging.personalize(
    { userIdentity: userIdentity, forceDepersonalize: true },
    () => {
        // Success callback
    }
);

Personalize but keep profile as Lead

If you want to do a personalization without promoting profile to Customer you can set keepAsLead parameter to true.

mobileMessaging.personalize(
    { userIdentity: userIdentity, keepAsLead: true },
    () => {
         // Success callback
    }
);

Standard attributes

You can set different standard attributes of a user, such as First name, Last name, Birthday etc.:

var user = {
    firstName: "John",
    lastName: "Doe",
    gender: "Male",
    birthday: "1968-02-10",
};

mobileMessaging.saveUser(
    user,
    user => {
        // Here you can use updated user instance
    }
);

Please note that saveUser() may return a USER_MERGE_INTERRUPTED error if you have provided an already existing Phone number, Email, or External User Id that are already taken by another existing user profile. In other words, that particular phone/email/externalUserId is a unique identifier of an already existing user, different from the one that this installation is currently personalized with. You can find more details about this, and other possible errors at Server errors. If you wish to personalize the app installation with another existing user, that is, merge current user with another one, please use our Personalize API or SDK method.

For editing any attributes of the existing user, perform fetchUser first to get server data. Setting values to null (and saving user afterwards) will remove them from the user.

Custom attributes

Apart from a list of standard attributes, each User can have a set of custom ones. These are commonly used to cover any use-cases for targeting and segmentation that are not covered by the platform out of the box. Custom attributes are key-value pairs. Keys are of string type, values can be of string, number (converted all to Decimal number type), boolean, date, datetime or list of objects data type. The SDK allows both getting and setting these custom attributes.

Difference between date and datetime types is that usage of date doesn't sync time to the server (e.g. "2020-11-30"), but with datetime we provide timestamp as well, which can be visible on the web.

var user = {
    customAttributes: {
        favoriteMeal: "pizza",
        bootSize: 9,
        installationDate: "2019-01-01",
        lastVisitDateTime: "2020-12-01T08:50:18Z",
        isSubscribed: true,
        height: null,
        favsList: [{
            id: "1",
            price: 99.99,
            sale: true
        },
        {
            id: "2",
            price: 149.99,
            sale: false
        }]
    }
};

mobileMessaging.saveUser(
    user
    , (user) => {
        // Here you can use updated user instance
        console.log('Success' + JSON.stringify(user));
    }, (error) => {
        console.log('Error' + JSON.stringify(error));
    });

With this data, you can segment users by using Segments and target them by their custom attribute values:

Create a Segment

List of objects

Detailed description on what list of objects is, some common use cases and how to set it on web are provided here. Mobile implementation specifics:

  • as provided in the upper example of updating custom attributes, list of objects can be set as a custom attribute, but this type is more complex
  • list of objects needs to be created on the web portal
  • it needs to have the same structure as on web when it's provided from SDK, otherwise error will be returned as an error response
  • supported types are: string, number, boolean, date and datetime

Tags

You can add or remove Tags from users based on their preferences or interests. Using Tags you can easily segment users which are interested in any specific topic and send messages only to such users.

var user = {
    tags: ["Promotions", "Transactions"]
};

mobileMessaging.saveUser(
    user,
    user => {
        // Here you can use updated user instance
    }
);

Afterwards you will see these tags in a user profile and will be able to segment such users when sending targeted messages or campaigns.

Broadcast by tag

If you have any questions or suggestions, feel free to send an email to [email protected] or create an issue.

Features and APIs

FAQ

Clone this wiki locally