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

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

• SDK добавлено в ваше мобильное приложение (в проекте появилась зависимость CarrotSDK)
• Ключи взяты из раздела для разработчика (не из webApi): ключи для SDK
• Инициализация выполнена успешно и приложение запустилось без ошибок
• В консоли появилась надпись “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).

Сложный формат для установки свойств представляет собой массив из объектов. Каждый объект — атомарная операция над свойством. В объекте три поля: op — операция, key — имя свойства, value — значение Поддерживаются следующие операции:

• update_or_create — наиболее часто используемый вариант. Если свойство уже существует, перезаписать
• set_once — записать только если свойства не существует
• add — добавить заданное значение к свойству (если свойства не существует, перед записью значения оно будет создано со значением 0)
• delete — удалить свойство
• append — добавить в список
• union — добавить в список, если еще не добавлен
• exclude — удалить из списка

Примеры:

[
    // Установить значение (если уже существует - обновить)
    {"op": "update_or_create", "key": "my_property", "value": "Hello"},

    // Установить только если свойство не задано
    {"op": "set_once", "key": "my_property", "value": "Hello"},

    // Инкремент, декремент, добавление и вычитание
    {"op": "add", "key": "my_property", "value": "1"},
    {"op": "add", "key": "my_property", "value": "-1"},
    {"op": "add", "key": "my_property", "value": "15"},
    {"op": "add", "key": "my_property", "value": "-53"},

    // Удалить свойство
    {"op": "delete", "key": "my_property", "value": "0"},

    // Добавить элемент в список
    {"op": "append", "key": "my_list_property", "value": "super-element"},

    // Добавить элемент в список только если его там еще нет ("добавить в множество")
    {"op": "union", "key": "my_list_property", "value": "super-element"},

    // Удалить элемент из списка
    {"op": "exclude", "key": "my_list_property", "value": "super-element"},
]

На данный момент максимальное количество элементов в списке — 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	Категории просмотренных товаров (список из названий категорий товаров)

Метод

Можно установить необходимые свойства с помощью следующего кода:

Swift

import CarrotSDK

let prop = UserProperty(key: "Key", value: "Value")
Carrot.shared.setUserProperty([prop])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

Carrot *carrot = [Carrot shared];
UserProperty *userProp = [[UserProperty alloc] initWithKey:@"Key" value:@"Value"];
[carrot setUserProperty:@[userProp]];

В данном примере prop это какое-то свойство, которое необходимо установить, однако, стоит обратить внимание, что функция setUserProperty принимает массив свойств. Поэтому в данном примере на Swift, prop обернут в [].

Класс UserProperty

Swift

import CarrotSDK

let prop = UserProperty(key: "Key", value: "Value")

Objective-C

#import "CarrotSDK/CarrotSDK.h"

UserProperty *userProp = [[UserProperty alloc] initWithKey:@"Key" value:@"Value"];

Обратите внимание, что любое значение свойства, описано в SDK как строка.

И не стоит забывать, о том что ключ, так же известный, как имя свойства не может начинаться со знака $ (это привилегия системных свойств)

Swift

let prop = UserProperty(
        key: "Key",
        value: "Value",
        operation: .updateOrCreate
)

Objective-C

UserProperty *userProp = [[UserProperty alloc] initWithKey:@"Key"
                                                     value:@"Value"
                                                 operation:UserPropertyOperationUpdateOrCreate];

Класс UserProperty имеет необязательное поле при инициализации: operation

Возможные варианты:

updateOrCreate	Если свойство уже существует, перезаписать, если нет - создать
setOnce	Записать только если свойства не существует
add	добавить заданное значение к свойству (если свойства не существует, перед записью значения, оно будет создано со значением 0)
delete	удалить свойство
append	добавить в список
union	добавить в список, если еще не добавлен
exclude	удалить из списка

Если не указывать этот параметр, то будет выбран параметр по умолчанию: updateOrCreate

Так же, стоит отметить, что operation имеет тип Enum, а значит Xcode подскажет синтаксис и возможные варианты, а так же это исключает возможность написать что-то свое в поле operation

Классы CarrotUserProperty и EcommerceUserProperty

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

Swift

import CarrotSDK

let systemProp = CarrotUserProperty(
        key: .name,
        value: "userName"
)

Objective-C

#import "CarrotSDK/CarrotSDK.h"

CarrotUserProperty *systemProp = [[CarrotUserProperty alloc] initWithKey:CarrotUserPropertyKeyName
                                                                   value:@"userName"];

Swift

import CarrotSDK

let storeProp = EcommerceUserProperty(
        key: .profit,
        value: "very much"
)

Objective-C

#import "CarrotSDK/CarrotSDK.h"

EcommerceUserProperty *storeProp = [[EcommerceUserProperty alloc] initWithKey:EcommerceUserPropertyKeyProfit
                                                                         value:@"very much"];

По аналогии с классом UserProperty, можно передать поле operation

Кейсы

Запись email

Swift

import CarrotSDK

let email = "a@b.c"
let systemProp = CarrotUserProperty(key: .email, value: email)
Carrot.shared.setUserProperty([systemProp])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

NSString *email = @"a@b.c";
CarrotUserProperty *systemProp = [[CarrotUserProperty alloc] initWithKey:CarrotUserPropertyKeyEmail
                                                                   value:email];
[[Carrot shared] setUserProperty:@[systemProp]];

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

Swift

import CarrotSDK

let timestampString = "2015-09-13T13:25:05"
let prop = UserProperty(
        key: "startTime",
        value: timestampString,
        operation: .delete
)
Carrot.shared.setUserProperty([prop])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

NSString *timestampString = @"2015-09-13T13:25:05";
UserProperty *prop = [[UserProperty alloc] initWithKey:@"startTime"
                                                 value:timestampString
                                             operation:UserPropertyOperationDelete];
[[Carrot shared] setUserProperty:@[prop]];

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

Swift

import CarrotSDK

let prop = UserProperty(
        key: "isOpenedApp",
        value: "true",
        operation: .setOnce
)
Carrot.shared.setUserProperty([prop])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

UserProperty *prop = [[UserProperty alloc] initWithKey:@"isOpenedApp"
                                                 value:@"true"
                                             operation:UserPropertyOperationSetOnce];
[[Carrot shared] setUserProperty:@[prop]];

Методы WebAPI

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

FAQ

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

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

Swift

import CarrotSDK

let prop = UserProperty(key: "$name", value: "userName")
Carrot.shared.setUserProperty([prop])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

UserProperty *prop = [[UserProperty alloc] initWithKey:@"$name" value:@"userName"];
[[Carrot shared] setUserProperty:@[prop]];

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

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

Swift

import CarrotSDK

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

Carrot.shared.setUserProperty([
        propInt,
        propStr,
        propBool,
        propDate,
        propList
])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

UserProperty *propInt = [[UserProperty alloc] initWithKey:@"propInt" value:@"145"];
UserProperty *propStr = [[UserProperty alloc] initWithKey:@"propStr" value:@"Hello, world!"];
UserProperty *propBool = [[UserProperty alloc] initWithKey:@"propBool" value:@"true"];
UserProperty *propDate = [[UserProperty alloc] initWithKey:@"propDate" value:@"2015-09-13T13:25:05"];
UserProperty *propList = [[UserProperty alloc] initWithKey:@"propList" value:@"["element1", "element2", "element3"]"];

[[Carrot shared] setUserProperty:@[
    propInt,
    propStr,
    propBool,
    propDate,
    propList
]];

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

Swift

import CarrotSDK

let number: Int = 64
let propInt = UserProperty(key: "propInt", value: String(number))
Carrot.shared.setUserProperty([propInt])

Objective-C

#import "CarrotSDK/CarrotSDK.h"

NSInteger number = 64;
UserProperty *propInt = [[UserProperty alloc] initWithKey:@"propInt"
                                                    value:[NSString stringWithFormat:@"%ld", (long)number]];
[[Carrot shared] setUserProperty:@[propInt]];