Передача Свойств

Убедитесь, что предыдущие шаги выполнены успешно

• SDK подключено к проекту: добавлена зависимость io.carrotquest:android-sdk (см. Установка)
• Ключи взяты из раздела для разработчика (не из webApi): Ключи для SDK
• Инициализация выполнена успешно и в Logcat появилась надпись “SDK init success”

Результат шага

• Свойства добавляются в карточку пользователя и отображаются корректно

Свойства пользователя

Полный список свойств можно посмотреть здесь

Здесь собрана различная информация о свойствах пользователя.

Не стоит путать свойства пользователя и свойства события. Свойства события отражают дополнительную информацию о событии (например, у события «Сделал заказ» могут быть свойства «Сумма», «Товары» и т.д.). Свойства пользователя отражают информацию о пользователе. Например, имя, email, количество заказов, сумма всех заказов и т.д.

Типы данных

Поддерживается пять типов данных:

• число
• строка
• дата/время
• логический (булев)
• список

Числа могут быть только целыми в диапазоне -2^53 .. +2^53, или -9007199254740992 .. +9007199254740992.

Максимальная длина строки 255 символов.

Элементами списка могут быть только строки длиной до 255 символов (максимум 30 элементов в списке).

Дата/время в формате ISO 8601: YYYY-MM-DDTHH:MM:SS. Допускается сокращённый вариант: YYYY-MM-DD (в этом случае будет подставлено время 00:00:00).

Пример:

{
    value1: 145,
    value2: "Hello, world!",
    value3: true,
    value4: "2015-09-13T13:25:05",
    value5: ["element1", "element2", "element3"]
}

Формат установки свойств

Иногда простой установки свойств недостаточно. Например, если вы отслеживаете количество нажатий на кнопку, было бы удобно каждый раз увеличивать значение свойства на единицу (операция add). Другой пример — вы хотите узнать, какой раздел пользователь посетил первым: свойство нужно записать только в том случае, если оно ещё не установлено (операция set_once).

В Carrot quest SDK для Android операция выбирается через enum UserProperty.Operation. Поддерживаются:

• UPDATE_OR_CREATE — наиболее часто используемый вариант. Если свойство уже существует — перезаписать, иначе создать. Используется по умолчанию.
• SET_ONCE — записать только если свойства ещё не существует.
• ADD — добавить заданное значение к свойству (если свойства не существует, перед записью оно будет создано со значением 0).
• DELETE — удалить свойство.
• APPEND — добавить элемент в список.
• UNION — добавить элемент в список, если его там ещё нет («добавить в множество»).
• EXCLUDE — удалить элемент из списка.

Особенности списков:

• максимум 30 элементов, элементами могут быть только строки;
• при APPEND порядок добавления сохраняется; при добавлении 31-го элемента не гарантируется, какой из старых будет вытеснен;
• при UNION порядок не сохраняется, но повторяющихся элементов не будет; если в списке уже 30 элементов, добавление не гарантируется.

См. также:

• Установка свойств в JavaScript API
• Установка свойств в Web API

Системные свойства пользователя

Все названия свойств, начинающиеся с символа $, считаются системными. Ваши собственные свойства не должны начинаться с $.

Разрешено изменять только 3 свойства: $name, $phone, $email. Все остальные системные свойства можно только читать.

Имя	Описание
$name	Имя
$email	Email
$phone	Телефон
$last_seen	Последняя активность, дата совершения последнего события
$last_contacted	Последний контакт, дата последнего ответа от пользователя или последней отправки сообщения пользователю (в том числе автосообщения)
$last_reply	Дата последнего ответа от пользователя
$conversations_emails	Количество диалогов по email
$conversations_chats	Количество диалогов с типом чат
$conversations_popups	Количество диалогов с типом поп-ап
$sessions	Количество сессий
$user_id	User ID
$score	Количество баллов (рейтинг)
$initial_referrer	Первый источник (реферрер)
$initial_referrer_domain	Первый источник (реферрер), но только домен
$initial_utm_campaign	Первая метка UTM Campaign
$initial_utm_source	Первая метка UTM Source
$initial_utm_medium	Первая метка UTM Medium
$initial_utm_content	Первая метка UTM Content
$initial_utm_term	Первая метка UTM Term
$last_utm_campaign	Последняя метка UTM Campaign
$last_utm_source	Последняя метка UTM Source
$last_utm_medium	Последняя метка UTM Medium
$last_utm_content	Последняя метка UTM Content
$last_utm_term	Последняя метка UTM Term
$country	Страна
$region	Регион
$city	Город
$latitude	Географическая широта
$longitude	Географическая долгота
$email_unsubscribed	Отписался от email
$avatar	Имя файла с аватаром. Аватарки пользователей лежат по адресу: https://files.carrotquest.io/avatars-users/
$social_vk	URL страницы ВКонтакте
$social_facebook	URL страницы Facebook
$social_fourqsuare	URL страницы Foursquare
$social_googleplus	URL страницы Google+
$social_pinterest	URL страницы Pinterest
$social_twitter	URL страницы Twitter
$social_skype	Skype

Устаревшие deprecated свойства: $comment, $last_active_user, $online, $idle, $cluster_id, $app_uid, $uid, $identity.

После первого совершения события у пользователя появляются три свойства, связанные с этим событием. Например, если событие имеет ID=123, появятся свойства:

Имя	Описание
$event_123_count	Сколько раз было совершено событие
$event_123_first	Дата, когда событие было совершено первый раз
$event_123_last	Дата, когда событие было совершено последний раз

Свойства для интернет-магазинов

Свойства, специфичные для интернет-магазинов. Эти свойства можно записывать через API.

Имя	Описание
$cart_amount	Сумма в корзине (целое число)
$viewed_products	Просмотренные товары (список из названий товаров)
$cart_items	Корзина (список из названий товаров)
$last_order_status	Статус последнего заказа
$last_payment	Сумма последнего заказа (целое число)
$revenue	Сумма всех заказов (целое число)
$profit	Доход с пользователя (целое число)
$group	Группа
$discount	Скидка (целое число)
$orders_count	Количество заказов (целое число)
$ordered_items	Заказанные товары (список из названий товаров)
$ordered_categories	Категории заказанных товаров (список из названий категорий товаров)
$viewed_categories	Категории просмотренных товаров (список из названий категорий товаров)

Метод

Установить свойство можно через Carrot.setUserProperty. Метод имеет несколько перегрузок: для одного свойства и для списка свойств.

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.UserProperty

val prop = UserProperty("Key", "Value")
Carrot.setUserProperty(prop)
// или сразу несколько:
Carrot.setUserProperty(listOf(prop1, prop2))

Java

import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.UserProperty;

UserProperty prop = new UserProperty("Key", "Value");
Carrot.setUserProperty(prop);
// или сразу несколько:
Carrot.setUserProperty(Arrays.asList(prop1, prop2));

Класс UserProperty

Kotlin

import io.carrotquest_sdk.android.models.UserProperty

val prop = UserProperty("Key", "Value")

Java

import io.carrotquest_sdk.android.models.UserProperty;

UserProperty prop = new UserProperty("Key", "Value");

Любое значение свойства в SDK представлено строкой. Ключ свойства не может начинаться с $ — это привилегия системных свойств.

Конструктор UserProperty имеет необязательное поле operation — операция над свойством (см. Формат установки свойств). Если операция не указана, используется UPDATE_OR_CREATE.

Kotlin

import io.carrotquest_sdk.android.models.UserProperty

val prop = UserProperty(
    operation = UserProperty.Operation.UPDATE_OR_CREATE,
    key = "Key",
    value = "Value"
)

Java

import io.carrotquest_sdk.android.models.UserProperty;

UserProperty prop = new UserProperty(
    UserProperty.Operation.UPDATE_OR_CREATE,
    "Key",
    "Value"
);

Классы CarrotUserProperty и EcommerceUserProperty

Для установки системных свойств можно использовать встроенные классы. В них поле ключа заменено на enum, чтобы выбрать свойство прямо из подсказок IDE — без риска опечататься в имени.

CarrotUserProperty — основные системные свойства ($name, $phone, $email):

Kotlin

import io.carrotquest_sdk.android.models.CarrotUserProperty

val systemProp = CarrotUserProperty(
    key = CarrotUserProperty.Property.NAME,
    value = "userName"
)

Java

import io.carrotquest_sdk.android.models.CarrotUserProperty;

CarrotUserProperty systemProp = new CarrotUserProperty(
    CarrotUserProperty.Property.NAME,
    "userName"
);

EcommerceUserProperty — свойства для интернет-магазинов ($cart_amount, $revenue, $orders_count и т.д.):

Kotlin

import io.carrotquest_sdk.android.models.EcommerceUserProperty

val storeProp = EcommerceUserProperty(
    key = EcommerceUserProperty.Property.PROFIT,
    value = "very much"
)

Java

import io.carrotquest_sdk.android.models.EcommerceUserProperty;

EcommerceUserProperty storeProp = new EcommerceUserProperty(
    EcommerceUserProperty.Property.PROFIT,
    "very much"
);

По аналогии с UserProperty, оба класса принимают необязательное поле operation.

Кейсы

Запись email

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.CarrotUserProperty

val email = "a@b.c"
val systemProp = CarrotUserProperty(
    key = CarrotUserProperty.Property.EMAIL,
    value = email
)
Carrot.setUserProperty(systemProp)

Java

import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.CarrotUserProperty;

String email = "a@b.c";
CarrotUserProperty systemProp = new CarrotUserProperty(
    CarrotUserProperty.Property.EMAIL,
    email
);
Carrot.setUserProperty(systemProp);

Удаление времени входа в апп

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.UserProperty

val timestampString = "2015-09-13T13:25:05"
val prop = UserProperty(
    UserProperty.Operation.DELETE,
    "startTime",
    timestampString
)
Carrot.setUserProperty(prop)

Java

import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.UserProperty;

String timestampString = "2015-09-13T13:25:05";
UserProperty prop = new UserProperty(
    UserProperty.Operation.DELETE,
    "startTime",
    timestampString
);
Carrot.setUserProperty(prop);

Одноразовая запись свойства о наличии установленного аппа у пользователя

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.UserProperty

val prop = UserProperty(
    UserProperty.Operation.SET_ONCE,
    "isOpenedApp",
    "true"
)
Carrot.setUserProperty(prop)

Java

import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.UserProperty;

UserProperty prop = new UserProperty(
    UserProperty.Operation.SET_ONCE,
    "isOpenedApp",
    "true"
);
Carrot.setUserProperty(prop);

Методы WebAPI

Если у вас возникли вопросы, вы можете посмотреть, как похожая механика работает в методах WebAPI, можно найти по ссылке: https://developers.carrotquest.io/webapi/endpoints/

FAQ

Что делать, если системного свойства не оказалось в SDK, но в WEB версии он есть?

Его можно передать с помощью обычного UserProperty. Но нужно быть аккуратным, бэк просто не запишет несуществующее системное свойство.

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.UserProperty

val prop = UserProperty("\$name", "userName")
Carrot.setUserProperty(prop)

Java

import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.UserProperty;

UserProperty prop = new UserProperty("$name", "userName");
Carrot.setUserProperty(prop);

Как передать другие типы свойств, такие же как на WEB версии?

Просто передав свойства в виде строки.

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.UserProperty

val propInt = UserProperty("propInt", "145") // Число
val propStr = UserProperty("propStr", "Hello, world!") // Строка
val propBool = UserProperty("propBool", "true") // Логический
val propDate = UserProperty("propDate", "2015-09-13T13:25:05") // Дата или время
val propList = UserProperty("propList", "[\"element1\", \"element2\", \"element3\"]") // Список

Carrot.setUserProperty(
    listOf(propInt, propStr, propBool, propDate, propList)
)

Java

import java.util.Arrays;
import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.UserProperty;

UserProperty propInt = new UserProperty("propInt", "145");
UserProperty propStr = new UserProperty("propStr", "Hello, world!");
UserProperty propBool = new UserProperty("propBool", "true");
UserProperty propDate = new UserProperty("propDate", "2015-09-13T13:25:05");
UserProperty propList = new UserProperty("propList", "[\"element1\", \"element2\", \"element3\"]");

Carrot.setUserProperty(Arrays.asList(
    propInt, propStr, propBool, propDate, propList
));

Дружеское напоминание: можно использовать встроенные в язык конвертеры. Например:

Kotlin

import io.carrotquest_sdk.android.Carrot
import io.carrotquest_sdk.android.models.UserProperty

val number: Int = 64
val propInt = UserProperty("propInt", number.toString())
Carrot.setUserProperty(propInt)

Java

import io.carrotquest_sdk.android.Carrot;
import io.carrotquest_sdk.android.models.UserProperty;

int number = 64;
UserProperty propInt = new UserProperty("propInt", String.valueOf(number));
Carrot.setUserProperty(propInt);