User Object

Initialize user object

Whenever you initialize Insider SDK, you also initialize a new Insider user object. You can set attributes for this object and get this object with the getCurrentUser method.

Insider user object represents the current user of your app. It is the main object you can use for attribution (e.g. age, email, opt-in, etc.).

Method Signature

public InsiderUser getCurrentUser()

fun getCurrentUser(): InsiderUser

Method Example

Insider.Instance.getCurrentUser();

The values in the method examples are sample values. While implementing these methods, you need to replace them with your own unique variables. Otherwise, the methods will not function properly and might cause discrepancies in user unification.

Set email as user identifier

This method allows you to set the user identifier attribute of your Insider user object for data unification. With this attribute, you can unify your user data within Insider products and reach this user via different channels such as mobile app and web.

Method Signature

public InsiderIdentifiers addEmail(String email)

fun addEmail(email: String): InsiderIdentifiers

Method Example

InsiderIdentifiers identifiers = new InsiderIdentifiers();
identifiers.addEmail("sample@mail.com");
identifiers.addPhoneNumber("+1234567");
identifiers.addUserID("CRM-ID");
Insider.Instance.getCurrentUser().login(identifiers);

All parameter types are required to be String.
Phone numbers must start with a + (plus) sign followed by a country code. The country code should start with a number between 1-9.

Set phone number as user identifier

Method Signature

public InsiderIdentifiers addPhoneNumber(String phoneNumber)

fun addPhoneNumber(phoneNumber: String): InsiderIdentifiers

Method Example

InsiderIdentifiers identifiers = new InsiderIdentifiers();
identifiers.addEmail("mobile@useinsider.com");
identifiers.addPhoneNumber("+901234567");
identifiers.addUserID("CRM-ID");
Insider.Instance.getCurrentUser().login(identifiers);

All parameter types are required to be String.
Phone numbers are required to start with a + (plus) sign followed by a country code. The country code should start with a number between 1-9.

Set user ID as user identifier

Method Signature

public InsiderIdentifiers addUserID(String userID)

fun addUserID(userID: String): InsiderIdentifiers

Method Example

InsiderIdentifiers identifiers = new InsiderIdentifiers();
identifiers.addEmail("mobile@useinsider.com");
identifiers.addPhoneNumber("+901234567");
identifiers.addUserID("CRM-ID");
Insider.Instance.getCurrentUser().login(identifiers);

All parameter types are required to be String.
Phone numbers are required to start with a + (plus) sign followed by a country code. The country code should start with a number between 1-9.

Set name attribute

This method allows you to set the name attribute for your Insider user object.

Parameter	Data Type
name	String

Method Signature

public InsiderUser setName(String name)

fun setName(name: String): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setName("name");

Set surname attribute

This method allows you to set the surname attribute for your Insider user object.

Parameter	Data Type
surname	String

Method Signature

public InsiderUser setSurname(String surname)

fun setSurname(surname: String): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setSurname("surname");

Set gender attribute

This method allows you to set the gender attribute for your Insider user object. You need to pass InsiderGender enum object as a parameter.

Parameter	Enum values
gender (InsiderGender enum)	InsiderGenderMale InsiderGenderFemale InsiderGenderOther

Method Signature

public InsiderUser setGender(InsiderGender gender)

fun setGender(gender: InsiderGender): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setGender(InsiderGender.OTHER);

Set age attribute

This method allows you to set the age attribute for your Insider user object.

Parameter	Data Type
age	Integer

Method Signature

public InsiderUser setAge(int age)

fun setAge(age: Int): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setAge(23);

Set birthday attribute

This method allows you to set the birthday attribute for your Insider user object.

Data should be set in (YYYY-MM-DD) format.

Parameter	Data Type
birthday	Date

Method Signature

public InsiderUser setBirthday(Date birthday)

fun setBirthday(birthday: Date): InsiderUser

Method Example

Date date = new Date(); 
Insider.Instance.getCurrentUser().setBirthday(date);

Select language attribute

This method allows you to set the language attribute for your Insider user object.

Parameter	Data Type
language	String

Method Signature

public InsiderUser setLanguage(String language)

fun setLanguage(language: String): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setLanguage("language");

Set email opt-in attribute

This method allows you to set the email opt-in (permission) attribute for your Insider user object.

Parameter	Data Type
emailOptin	Boolean

Method Signature

public InsiderUser setEmailOptin(boolean emailOptin)

fun setEmailOptin(emailOptin: Boolean): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setEmailOptin(true);

Set SMS opt-in attribute

This method allows you to set the SMS opt-in (permission) attribute for your Insider user object.

Parameter	Data Type
smsOptin	Boolean

Method Signature

public InsiderUser setSMSOptin(boolean smsOptin)

fun setSMSOptin(smsOptin: Boolean): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setSMSOptin(true);

Set WhatsApp opt-in attribute

This method allows you to set the WhatsApp opt-in (permission) attribute for your Insider user object.

Parameter	Data Type
whatsAppOptin	Boolean

Method Signature

public InsiderUser setWhatsappOptin(boolean whatsAppOptin)

fun setWhatsappOptin(whatsappOptin: Boolean): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setWhatsappOptin(true);

Set push opt-in attribute

This method allows you to set the push opt-in (permission) attribute for your Insider user object.

If you pass the value as false, the respective device will not receive any push notifications unless you set the value to true.

Parameter	Data Type
pushOptin	Boolean

Method Signature

public InsiderUser setPushOptin(boolean pushOptin)

fun setPushOptin(pushOptin: Boolean): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setPushOptin(true);

Set location opt-in attribute

This method allows you to set the location opt-in (permission) attribute for your Insider user object.

If you pass the value as false, the respective device will not be targeted for Geofence unless you set the value to true.

Parameter	Data Type
locationOptin	Boolean

Method Signature

public InsiderUser setLocationOptin(boolean locationOptin)

fun setLocationOptin(locationOptin: Boolean): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setLocationOptin(true);

Set promotional opt-in attribute

This method allows you to set the promotional opt-in (permission) attribute for your Insider user object. It stores the user's consent for promotional marketing messages so that it can be used for App Push targeting.

If you never call this method, or if you pass the value as false, the user is treated as not opted-in and will not be targeted by promotional App Push campaigns.

This attribute is stored at the user (profile) level, not per device, so its value applies to every device the user is identified on.

The method returns the InsiderUser object, so it can be chained with the other user attribute setters.

Parameter	Data Type
promotionalOptin	Boolean

Method Signature

public InsiderUser setPromotionalOptin(boolean promotionalOptin)

Method Examples

Insider.Instance.getCurrentUser().setPromotionalOptin(true);

Insider.Instance.currentUser.setPromotionalOptin(true)

Set login attribute

This method allows you to set the login status attribute for your Insider user object.

Once you call this method to assign its value as true, you need to call the logout method to set it to false.

Method Signature

public InsiderUser login()

fun login()

Method Example

InsiderIdentifiers identifiers = new InsiderIdentifiers(); 
identifiers.addEmail("sample@mail.com")
            .addPhoneNumber("+1234567")
            .addUserID("CRM-ID"); 
Insider.Instance.getCurrentUser().login(identifiers);

Login with completion handler

The completion variant returns the resolved Insider ID after login(...) finishes on the server useful for syncing the ID with your own backend immediately after unification.

Method Signature

public void login(InsiderIdentifiers identifiers, InsiderIDResult insiderIDResultInterface)

 public interface InsiderIDResult {
     void insiderIDResult(String insiderID);
 }

fun login(identifiers: InsiderIdentifiers, insiderIDResultInterface: InsiderIDResult)

 fun interface InsiderIDResult {
     fun insiderIDResult(insiderID: String?)
 }

Method Example

InsiderIdentifiers identifiers = new InsiderIdentifiers()
         .addEmail("sample@mail.com")
         .addPhoneNumber("+901234567")
         .addUserID("CRM-ID");

 Insider.Instance.getCurrentUser().login(identifiers, insiderId -> {
     if (insiderId != null) {
         MyBackend.shared().linkInsiderId(insiderId);
     }
 });

val identifiers = InsiderIdentifiers()
     .addEmail("sample@mail.com")
     .addPhoneNumber("+901234567")
     .addUserID("CRM-ID")

 Insider.Instance.getCurrentUser().login(identifiers) { insiderId ->
     insiderId?.let { MyBackend.shared.linkInsiderId(it) }
 }

Set logout attribute

This method allows you to set the login status attribute for your Insider user object.

Once you call assign false for the value for login status, you need to call the login method to set it to true.

Method Signature

public void logout()

fun logout()

Method Example

Insider.Instance.getCurrentUser().logout;

Set logout-reset attribute

This is an alternative logout method for specific use cases. If you're unsure whether it applies to your setup, please contact your account manager. If you don’t have a special requirement, use the default logout method to avoid user-management issues or unexpected MAU increases.

This method allows you to set the login status attribute for your Insider user object, then disassociate the user from the current device and generate new IID for the current device.

Also, this method allows you to send additional Identifiers to include in the logout process, all additional identifiers (including the currently logged in user) will be disassociated from the current device.

Once you call assign false for the value for login status, you need to call the login method to set it to true.

Method Signature

public void logoutResettingInsiderID(InsiderIdentifiers[] additionalIdentifiers)

fun logoutResettingInsiderID(additionalIdentifiers: Array<InsiderIdentifiers>?)

Method Example

// Logout the current user only
Insider.Instance.getCurrentUser().logoutResettingInsiderID(null);

// Logout the current user along side additional users
InsiderIdentifiers insiderIdentifiers = new InsiderIdentifiers()
        .addEmail("sample@mail.com")
        .addPhoneNumber("+1234567890")
        .addUserID("CRM-ID");

Insider.Instance.getCurrentUser().logoutResettingInsiderID(new InsiderIdentifiers[]{insiderIdentifiers});

Set sign up event

To trigger action for the signup of users, you need to call this method whenever a user signs up to the app.

Method Signature

public void signUpConfirmation()
 public void signUpConfirmation(Map<String, ?> customParameters)

fun signUpConfirmation()
 fun signUpConfirmation(customParameters: Map<String, *>)

Method Example

// Without parameters
 Insider.Instance.signUpConfirmation();

 // With custom parameters
 Map<String, Object> params = new HashMap<>();
 params.put("source", "organic");
 Insider.Instance.signUpConfirmation(params);

// Without parameters
 Insider.Instance.signUpConfirmation()

 // With custom parameters
 val params = mapOf("source" to "organic")
 Insider.Instance.signUpConfirmation(params)

Set locale attribute

This method allows you to set the locale attribute for your Insider user object.

Parameter	Data Type
locale	String

Method Signature

public InsiderUser setLocale(String locale)

fun setLocale(locale: String): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setLocale("en_EN");

Set custom string attribute

This method allows you to set the custom string attribute for your Insider user object.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String
value	String

Method Signature

public InsiderUser setCustomAttributeWithString(String key, String value)

fun setCustomAttributeWithString(key: String, value: String): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setCustomAttributeWithString("key", "stringValue");

Set custom integer attribute

This method allows you to set the custom integer attribute for your Insider user object.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String
value	Integer

Method Signature

public InsiderUser setCustomAttributeWithInt(String key, int value)

fun setCustomAttributeWithInt(key: String, value: Int): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setCustomAttributeWithInt("key", 10);

Set custom boolean attribute

This method allows you to set the custom boolean attribute for your Insider user object.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String
value	Boolean

Method Signature

public InsiderUser setCustomAttributeWithBoolean(String key, boolean value)

fun setCustomAttributeWithBoolean(key: String, value: Boolean): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setCustomAttributeWithBoolean("key", true);

Set custom double attribute

This method allows you to set the custom double attribute for your Insider user object.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String
value	Double

Method Signature

public InsiderUser setCustomAttributeWithDouble(String key, double value)

fun setCustomAttributeWithDouble(key: String, value: Double): InsiderUser

Method Example

Insider.Instance.getCurrentUser().setCustomAttributeWithDouble("key", 10.5);

Set custom date attribute

This method allows you to set the custom date attribute for your Insider user object.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String
value	Date object

Method Signature

public InsiderUser setCustomAttributeWithDate(String key, Date value)

fun setCustomAttributeWithDate(key: String, value: Date): InsiderUser

Method Example

Date date = new Date();
Insider.Instance.getCurrentUser().setCustomAttributeWithDate("key", date);

Set custom array attribute

This method allows you to set the custom array attribute for your Insider user object.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String
value	Array (of string)

Method Signature

public InsiderUser setCustomAttributeWithArray(String key, String[] value)

fun setCustomAttributeWithArray(key: String, value: Array<String>): InsiderUser

Method Example

String[] myArray = {"value1", "value2", "value3"};
Insider.Instance.getCurrentUser().setCustomAttributeWithArray("key", myArray);

Unset custom attribute

This method allows you to unset any custom attribute of your Insider user object. This method will remove the respective custom attribute of your user for the given key permanently.

Your attribute key should be lowercase and should not include any special character, non-Latin character, or any space. Otherwise, this attribute will be ignored. You can use underscores.

Parameter	Data Type
key	String

Method Signature

public InsiderUser unsetCustomAttribute(String key)

fun unsetCustomAttribute(key: String): InsiderUser

Method Example

Insider.Instance.getCurrentUser().unsetCustomAttribute("key");

Add objects to a custom attribute

This method allows you to add objects to an Array of Objects custom attribute of your Insider user object. Define the Array of Objects structure in the Insider One panel first. The SDK never creates or changes these definitions. Keys that are not defined in the panel are ignored, and the call still succeeds.

These rules apply to the add, merge, and remove methods for Array of Objects custom attributes:

The attribute key, every key inside the objects, and every key in value must be lowercase, with no special or non-Latin characters. Other keys are ignored. An invalid key in match drops the whole call instead, as described in the merge and remove sections.
Data that breaks a limit is dropped before sending, and each drop is logged. This covers key naming, strings longer than 500 characters, more than two nesting levels, an Array of Objects inside an object, arrays with mixed item types, and too many keys per object.
The object and key limits come from your account settings. Without them, the SDK uses 50 objects and 20 keys per object.
Attribute updates are sent in the order you call the methods. Updates that are not yet sent are dropped on logout or when the Insider ID changes.

Parameter	Data Type	Description
key	String	Name of the Array of Objects custom attribute.
objects	List<Map<String, Object>>	Objects to add to the attribute.

Method Signature

public InsiderUser addObjectsToCustomAttribute(String key, List<Map<String, Object>> objects)

fun addObjectsToCustomAttribute(key: String, objects: List<Map<String, Any>>): InsiderUser

Method Example

import com.useinsider.insider.InsiderUser;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

void addOrders(InsiderUser user) {
    Map<String, Object> order = new HashMap<>();
    order.put("id", "a1");
    order.put("status", "shipped");
    order.put("price", 120);

    List<Map<String, Object>> orders = new ArrayList<>();
    orders.add(order);

    user.addObjectsToCustomAttribute("orders", orders);
}

import com.useinsider.insider.InsiderUser

fun addOrders(user: InsiderUser) {
    val orders = listOf(
        mapOf<String, Any>("id" to "a1", "status" to "shipped", "price" to 120)
    )
    user.addObjectsToCustomAttribute("orders", orders)
}

addObjectsToCustomAttribute drops objects that fail validation. If no object is left, or the list is null or empty, the call is ignored, and a warning is logged.

Merge objects in a custom attribute

This method allows you to update the objects that match match in an Array of Objects custom attribute with the keys in value.

Parameter	Data Type	Description
key	String	Name of the Array of Objects custom attribute.
match	Map<String, Object>	Keys and values that identify the objects to update. Required.
value	Map<String, Object>	Keys and values to write into the matching objects. Required.

Method Signature

public InsiderUser mergeObjectsInCustomAttribute(String key, Map<String, Object> match, Map<String, Object> value)

fun mergeObjectsInCustomAttribute(key: String, match: Map<String, Any>, value: Map<String, Any>): InsiderUser

Method Example

import com.useinsider.insider.InsiderUser;

import java.util.HashMap;
import java.util.Map;

void markOrderDelivered(InsiderUser user) {
    Map<String, Object> match = new HashMap<>();
    match.put("id", "a1");

    Map<String, Object> value = new HashMap<>();
    value.put("status", "delivered");

    user.mergeObjectsInCustomAttribute("orders", match, value);
}

import com.useinsider.insider.InsiderUser

fun markOrderDelivered(user: InsiderUser) {
    user.mergeObjectsInCustomAttribute(
        "orders",
        mapOf<String, Any>("id" to "a1"),
        mapOf<String, Any>("status" to "delivered")
    )
}

Invalid keys in value are dropped. If any part of match fails validation, the whole call is dropped, so an invalid match never updates objects you did not intend to.

Remove objects from a custom attribute

This method allows you to remove the objects that match match from an Array of Objects custom attribute.

Parameter	Data Type	Description
key	String	Name of the Array of Objects custom attribute.
match	Map<String, Object>	Keys and values that identify the objects to remove. Pass null to remove every object.

removeObjectsFromCustomAttribute(key) removes every object from the attribute, the same as passing a null match.

Method Signature

public InsiderUser removeObjectsFromCustomAttribute(String key, Map<String, Object> match)

public InsiderUser removeObjectsFromCustomAttribute(String key)

fun removeObjectsFromCustomAttribute(key: String, match: Map<String, Any>?): InsiderUser

fun removeObjectsFromCustomAttribute(key: String): InsiderUser

Method Example

import com.useinsider.insider.InsiderUser;

import java.util.HashMap;
import java.util.Map;

void removeOrder(InsiderUser user) {
    Map<String, Object> match = new HashMap<>();
    match.put("id", "a1");

    user.removeObjectsFromCustomAttribute("orders", match);
}

import com.useinsider.insider.InsiderUser

fun removeOrder(user: InsiderUser) {
    user.removeObjectsFromCustomAttribute("orders", mapOf<String, Any>("id" to "a1"))
}

Removing every object cannot be undone, and the SDK logs a warning when you do it. An empty match is ignored with a warning, and a match that fails validation drops the whole call.

Get Insider ID

You can retrieve the Insider ID of the current user using the following methods.

Method signatures

public String getInsiderID()

fun getInsiderID(): String?

Method examples

String insiderId = Insider.Instance.getInsiderID();

val insiderId = Insider.Instance.getInsiderID()

For troubleshooting, refer to Why cannot we trigger the login method a second time in an active session, Confusion of attributes among users after login