Mesibo Profile and Contact Syncronization APIs

Estimated reading time: 15 minutes

A profile allows you to associate human-readable information such as name, description, picture, status, presence information, etc. with a user or a group.

There are three types of profiles:

Self Profile

The profile of the logged-in user. The user can modify self profile and publish it so that other users can view the profile information. All other users who have subscribed to this user’s profile will get instant notification of the profile change. The logged-in user can set the privacy of the profile to override the subscription, for example, only limited users can access the profile, not all subscribers.

User Profile

The profile of another user. Any user can request the profile of another user. If the profile exists locally, Mesibo API will instantly return it. If not, it will return an empty profile and also request the mesibo server for the profile. If the server has the profile and the user is allowed to access it, the user will be notified of the updated profile in a listener callback (explained later). Mesibo API will also invoke a callback whenever there is an update.

Group Profile

Group Profile is the same as User Profile described above except that the group profile can be modified only by the group owner or the admin having permission to modify it. All the group members will get instant notification of the pro

Getting Profile of another User or a Group

You can get the profile of any user or a group by calling getProfile API. If the profile exists locally, Mesibo API will instantly return it. If not, it will return an empty profile and also request the mesibo server for the profile.

There are no setters or set APIs to directly set a profile object. You must use getters, to first get a profile object and then use methods to modify individual properties. See MesiboProfile to learn more.

In Java,

MesiboProfile profile;
profile = Mesibo.getProfile(address);

String name = profile.getName();
Bitmap tn = profile.getThumbnail();

In Kotlin

var mProfile: MesiboProfile? = null
mProfile = Mesibo.getProfile(address)

String name:String = profile.getName();
var tn:Bitmap = profile.getThumbnail();

In Objective-C,

MesiboProfile *profile;
profile = [MesiboInstance getProfile:address groupid:0];

// get profile information
NSString *name = [profile getName]
UIImage *tn = [profile getThumbnail];

In Swift,

var mProfile: MesiboProfile!
profile = Mesibo.getInstance()?.getProfile(nil, groupid: 96568)

// get profile information
var name: String = mProfile.getName();
var image: UIImage = mProfile.getThumbnail()

In Javascript

var profile;
profile = Mesibo.getProfile(address);


var name = profile.getName();
var tn = profile.getThumbnail();

Subscribing to a Profile

You can subscribe to a profile so that you can be notified whenever changes are made to the profile. Note that, every time you call getProfile and if the profile does not exist locally, you will be automatically subscribed to the profile updates. However, you can change the subscription status anytime later by calling subscribe API. For example,

profile.subscribe(false); 

Note: You will receive a blank profile if you do not have access to a profile as per visibility rules set by the publisher of the profile (explained later). However, you can still subscribe to the profile and wait for the publisher to change the visibility settings in the future so that it is accessible to you.

After you subscribe to a profile, you will be notified whenever the profile is updated through the listeners - either through the global listener or per profile listener. See the section on Listeners to learn more about this.

Overriding Profile Information (Local Override)

You can override the profile information set by the user or group admin by calling various set methods. These changes will be local only and will not affect the global profile. For example,

profile.setName("New Name");
profile.save(); // save local changes to the database

The next time, getName API will return the updated profile information.

To restore a property to the original value and undo your local changes, set the property to null.

To restore the entire profile object to its original values and undo all local changes, you can call the removeLocalProfile method of the profile object.

Publishing your Profile

You can publish your profile so that other users will be able to access it as explained above. To publish a profile, you need to access MesiboSelfProfile object and set the required information.

To get your self profile use getSelfProfile. You can then modify properties of this profile, such as name, photo, address, etc.

MesiboSelfProfile selfProfile = Mesibo.getSelfProfile();

selfProfile.setName("John Doe");
selfProfile.setStatus("Hey! I am using this app.");
selfProfile.setImage(bitmap);
selfProfile.save(); // publish 

Every time you save the self profile, it will be published and all the subscribers will be automatically notified about it.

Profile Visibility

In addition to other information, you can control who can view your profile by setting the profile visibility. It can be one of the following:

PUBLIC

Anyone and everyone can view your profile. Any user can get your profile and subscribe to updates. By default, the profile visibility is PUBLIC.

CONTACTS/SELECTED ONLY

Only users who you have added as your contact will be able to get your profile and subscribe to your profile updates. You can add a profile as your contact using the setContact method. You can further specify what information a particular contact has access to. You can refer to Contact Synchronization section to learn more about contacts APIs.

NONE

Only you will have access to your profile and it will be invisible to others

selfProfile.setVisibility(MesiboProfile.VISIBILITY_PUBLIC);

Profile Publishing Mode

By default, every time you publish your profile, it will be synchronized immediately and all the valid subscribers will be notified immediately. However, you can change this behavior to on-demand by setting the publish mode. There are two modes:

Real-Time Publishing

As soon as you publish the profile all interested users will be notified immediately.

Lazy / On-demand Publishing

Once you publish your profile it will be updated on the server but other users will not be notified immediately. Instead, they will be notified along with other profiles or messages. This consumes lesser bandwidth than the Real-Time publishing. For example, in the case of a messaging app, if you have 1000 contacts using the app, and all thousand contacts have updated their profile in Lazy mode, the changes will not be reflected immediately. When you open their profile to view them or when you open their chat view and send/receive messages, their displayed profile can be updated.

selfProfile.setSyncType(MesiboProfile.SYNCTYPE_REALTIME);

Publishing or Updating Group Profile

Publishing group profile is the same as publishing self profile except that you need to get Group Profile instead of Self Profile and you must be either group owner or an admin with modify permissions.

Profile Listeners

There are two types of profile listeners in the mesibo Profile API:

Global Profile Listener - Mesibo.ProfileListener

Your app must implement the Mesibo.ProfileListener to be notified of global profile events - either when a profile that you have subscribed to has been updated on the server, or a profile is being accessed.

The following global listeners are a part of Mesibo.ProfileListener:

Mesibo_onProfileUpdated

Mesibo_onProfileUpdated is called when a profile that you have subscribed to is updated globally.

void Mesibo_onProfileUpdated(MesiboProfile profile){
  // Updated profile object recieved 
}

Mesibo_onGetProfile

Mesibo_onGetProfile is called whenever your app accesses a profile. You can make modifications to the profile object here as per your local context. For example, if you are syncing profiles of contacts on your phone, you may change the name on a user’s profile as per your local address book. Note that this listener will only be called for the first time you access a profile.

If the app makes modifications to the original profile make the listener return true. If no modifications were made return false.

boolean Mesibo_onGetProfile(MesiboProfile profile){
  // This profile was accessed
  // Make modifications to the profile

  return true;
}

Once you implement Mesibo.ProfileListener, add that as a listener as follows:

Mesibo.addListener(this);

Per Profile Listener - MesiboProfile.Listener

There are situations where you need to set a listener for particular profiles only. For example, in a messaging app, say you have expanded a profile. For now, you are only concerned about being notified of updates for a selected profile. So, set the listener only for selected profile.

To set a listener for each profile, implement MesiboProfile.Listener and set it.

The following listener is available in MesiboProfile.Listener:

void MesiboProfile_onUpdate(MesiboProfile profile){
  // This profile has been updated
}

Once you implement a MesiboProfile.Listener, set the listener for that profile as follows:

profile.addListener(mProfileSelected);
// mProfileSelected implements `MesiboProfile.Listener`

Saving a Profile

You also save a profile locally to the local database using the save method.

profile.save()

There are three possibilities when you are calling save on a profile object:

  1. If the profile is a self profile, the save method saves the profile to the local database and then publishes the latest profile to the server.
  2. If the profile is a group profile and you have modification permission, the save method saves the profile to the local database and then publishes the latest profile to the server.
  3. Otherwise, the save method saves the profile into the local database.

Blocking Profiles

To avoid messages/calls from a user/group, you can block their profile.

To block messages from a profile,

profile.blockMessages(true);

To block calls from a profile,

profile.blockCalls(true);

To unblock a profile, simply pass false.

For example,

profile.blockMessages(false);

Profile Image Handling

One can set the display picture of a profile using the following methods in a profile object:

  • setImage, Set the image bitmap
  • setImageFromFile, Set image from the path to the image file
  • setImageUrl, Set the file url of the image. For example, if you have uploaded the file to an external file server(Ex: Amazon S3 bucket) and obtained a url, you can directly set it.

If you set the image bitmap using setImage or setImagePath, mesibo will upload it to a file server and automatically generate a file url for you. To custom handle file uploads, you need to set up your own file server(Example, an Amazon S3 bucket) and implement an upload handler. Else, mesibo will use the default file handler to upload the image to mesibo servers. Once, the upload is complete mesibo will set the image url in the profile object and save.

Similarly, On the remote end, when someone gets your profile object, mesibo will download the image Once the download is complete, the file is cached. A thumbnail will also be automatically generated and saved for the profile, which can be accessed using the getThumbnail method.

to optimize bandwidth, mesibo only downloads images when needed. The image data may not be updated if you haven’t accessed a profile for a long time. For example, if a profile is updated and you use getImage, if the download is not complete you may get null. But, once the download is complete you will be notified through the listeners that the profile is updated. You can then read the latest profile object and display the updated profile picture.

Contact Synchronization

Contact Synchronization allows you to mark selected addresses as contacts, subscribe to their update, and also set the visibility of your profile to a particular contact. You need to use syncContacts or syncContact API for the Contact Synchronization

void syncContacts(String[] addresses, boolean addContact, boolean subscribe, int visibility, boolean, syncNow);
void syncContact(String address, boolean addContact, boolean subscribe, int visibility, boolean, syncNow);
void syncContacts();

syncContacts takes the following parameters:

Parameter Description
addresses Array of User addresses to be synced
addContact Pass true to add the user as a contact, false otherwise
subscribe Pass true to be notified when the user profiles are updated, false otherwise
visibility how your profile is visible to these addresses
syncNow Sync immediately or keep adding to the sync queue. Once you are done retrieving contacts, you may complete sync in one shot, by passing an empty addresses array and passing true to syncNow. mesibo will handle all this in the background for you

Once you call syncContacts, mesibo will match the list of addresses provided with the profile on the global server. You will then receive the profiles of matching contacts through the listener Mesibo_onProfileUpdated.

Example,

String[] contacts = {"18005550001", "18005550002", "18005550003"};
Mesibo.syncContacts(contacts, true, true, 0, true);

If you have queued contacts and would like to sync all these contacts you can call it as follows,

Mesibo.syncContacts();

To sync a single contact, you can use the syncContact method as follows:

Mesibo.syncContact(address, true, true, 0, true);

Adding Non-existing users as contacts

In addition to existing users, mesibo allows you to add and subscribe to non-existing users as contacts. This allows you to be notified automatically when those contacts join the app (for example, in WhatsApp or Telegram app, you are notified when one of your contacts joins the app).

You can refer to the Mesibo Messenger app source code to learn how contact sync and profile APIs are used.

Reference

The Profile API consists of the following:

  • MesiboProfile, To publish and subscribe to a profile, use methods from the MesiboProfile class. The MesiboSelfProfile class is a subclass of MesiboProfile
  • listeners, Listeners through which you will be notified about profile updates.

Refer to individual documentation to learn more.

profile, android, ios, javascript, contact, sync, group profile