Створення додаткових полів

Додаткові поля в картках контактів призначені для зберігання специфічних даних про контакти: персональних промокодів, важливих дат, локації тощо. Ці дані можна використовувати для розширеної сегментації та глибшої персоналізації комунікації.

Вкладка «Додаткові поля»

Списки додаткових полів доступні в налаштуваннях акаунту на вкладці Додаткові поля. За замовчуванням доступний лише список Personal із полями День народження та Стать.

У списку додаткових полів відображаються:

1. Тип поля (текстове поле, дата тощо).
2. Назва поля.
3. Змінна для автоматичного підставляння значення поля в повідомлення.
4. ID поля.
5. Кнопка редагування поля.
6. Кнопка видалення поля.

Ви можете створювати списки та додавати до них поля.

Створення списку

Списки допомагають групувати поля за призначенням, наприклад особисті дані або товарні вподобання. Щоб створити список полів:

1. Натисніть Новий список полів.

2. Введіть назву списку.

3. За потреби змініть ключ персоналізації, автоматично згенерований на основі назви. Ключ використовується для формування змінних полів цього списку, тому краще вибрати короткий і зрозумілий варіант.

4. Натисніть Зберегти.

Додавання полів

1. Натисніть плюс, щоб створити поле у списку.

2. Вкажіть назву поля та за потреби відредагуйте автоматично згенерований ключ персоналізації.

3. Виберіть тип поля. За замовчуванням вибрано Текстове поле.

Перейменування поля безпечне: система звертається до полів за внутрішнім ID, а не за назвою, тож раніше зібрані дані не втрачаються.

Типи полів

Залежно від типу контактних даних у системі доступні такі типи полів:

• Текстове поле може містити до тисячі символів, зокрема літери й цілі числа. Спеціальні символи не підтримуються. Цей тип можна використовувати, наприклад, для зберігання імені або адреси контакту.
• Текстова область може містити до п’яти тисяч символів, зокрема літери й цілі числа. Спеціальні символи не підтримуються. Цей тип можна використовувати, наприклад, для зберігання відповідей на розгорнуті запитання.
• Число може містити лише цілочисельні значення від -2147483647 до 2147483647, наприклад ID замовлення або кількість бонусів.
• Дробове число може містити цілі та дробові значення, наприклад суму замовлень.
• Дата — значення потрібно передавати у форматі ISO 8601: YYYY-MM-DD. Параметр Регулярна дата використовується для створення умовних груп для комунікації, пов’язаної з повторюваними подіями, наприклад річницею або днем народження.

• Дата з часом — прийнятні формати: YYYY-MM-DDTHH:mm:ssZ для UTC або YYYY-MM-DDTHH:mm:ss±HH:mm зі зміщенням від UTC. Час у форматі Unix не приймається: перетворіть значення в один із цих форматів. Значення зберігається таким, як ви його передали: система не приводить його до єдиного часового поясу, тож передане зміщення зберігається. Використовуйте цей тип для значень дати й часу, наприклад періоду дії промокоду.
• Випадаючий список містить заздалегідь визначені значення, наприклад стать, статус або мову контакту.

Якщо значення не відповідає типу поля, наприклад, дробове число передано в поле типу Число, запит на оновлення контакту відхиляється повністю: інші поля з цього запиту теж не зберігаються.

• Чекбокс дозволяє зберігати кілька вибраних значень.

Як побачити фактичні значення поля перед побудовою умови

Перелік значень, які реально записані в кастомне поле, видно в картці контакту та на вкладці додаткових полів контакту — відкрийте кілька контактів і подивіться, у якому вигляді значення зберігаються.

Коли будуєте умову сегмента за кількома значеннями одного поля, використовуйте оператор один з і додавайте кожне значення окремим пунктом. Перелічення кількох значень через кому в одному полі не працює — таке значення сприймається як один суцільний рядок.

Унікальність значень додаткових полів

Для додаткового поля не можна встановити вимогу унікальності. Однакове значення може бути записано в кількох контактах, і система не позначає такі збіги як дублікати.

В інтерфейсі немає окремого пошуку дублікатів за додатковими полями. Щоб знайти однакові значення, експортуйте контакти у CSV і порівняйте їх на своєму боці. Не вмикайте перемикач Експортувати тільки Email, щоб у файл потрапили всі поля — див. Робота з контактами: вкладка «Усі контакти».

Робота з додатковими полями через API

Створення полів

Спершу створіть поле в інтерфейсі, потім отримайте його ID методом Get additional fields і передавайте цей ID разом із даними контакту. Через API записуються значення в наявні поля, а самі поля не створюються.

Врахуйте це, коли налаштовуєте кілька акаунтів: структуру полів відтворюють у кожному окремо через інтерфейс. Що ще не переноситься, описано в статті Перенесення контенту між акаунтами.

Отримання списку полів

Щоб отримати списки додаткових полів, їхні ID, ключі, типи та допустимі значення, використовуйте метод Get additional fields:

GET /api/v1/additionalfields

ID із параметра additionalFields[].id у відповіді можна передавати в fields[].id під час додавання або оновлення контактів.

Після створення додаткового поля системі може знадобитися до години на синхронізацію. До її завершення поле може бути недоступним через API.

Оновлення поля типу «Чекбокс»

Щоб записати або оновити значення поля типу Чекбокс за допомогою API-методу Add/update contacts, передайте числовий ID поля в масиві fields. Кілька значень у параметрі value розділяйте комами:

{
  "contacts": [
    {
      "channels": [
        {
          "type": "email",
          "value": "[email protected]"
        }
      ],
      "fields": [
        {
          "id": 87166,
          "value": "Chinese,Italian"
        }
      ]
    }
  ],
  "dedupeOn": "email",
  "customFieldsIDs": [
    87166
  ]
}

У масиві customFieldsIDs вкажіть ID додаткових полів, які потрібно оновити. Під час оновлення наявного контакту цей параметр є обов’язковим. Система оновить лише поля, перелічені в масиві.

Значення поза переліком допустимих для поля запит відхиляє з кодом 400 і повідомленням '<field name>[<id>]' does not support value '<value>', де в лапках стоїть назва поля, а не його тип. Порожнє значення помилки не викликає: воно очищає поле, і в наступній відповіді контакт повертається вже без нього.

Масове очищення значення поля

Окремої дії, щоб очистити додаткове поле одразу в багатьох контактів, немає. Скористайтеся одним із двох способів:

• Повторно імпортуйте контакти з порожньою колонкою цього поля, увімкнувши імпорт порожніх значень.
• Надішліть запит Add/update contacts, указавши ID поля в customFieldsIDs і порожнє значення.

Оновлення додаткових полів через SDK

Щоб оновити додаткові поля через SDK, передавайте ключ персоналізації поля — пару СПИСОК.ПОЛЕ, наприклад TRAININGAPP.GOAL.

Ключ персоналізації показано у вікні редагування поля. Змінна в списку полів — це формат для підставляння в повідомлення: вона відображається у фігурних дужках і малими літерами. Для SDK копіюйте значення поля Ключ персоналізації.

Приклад для Android:

val userAttributes = UserAttributes(
    email = user.email,
    fields = listOf(
        UserCustomField(
            key = "TRAININGAPP.GOAL",
            value = "lose weight"
        )
    )
)

val user = User(userAttributes = userAttributes)

application.getRetenoInstance().setUserAttributes(
    "USER_ID",
    user
)

Приклад для iOS:

let userAttributes = UserAttributes(
    email: user.email,
    fields: [
        UserCustomField(
            key: "TRAININGAPP.GOAL",
            value: "lose weight"
        )
    ]
)

Reteno.updateUserAttributes(
    externalUserId: "USER_ID",
    userAttributes: userAttributes
)

Докладніше про мобільний SDK →

Додаткові поля в інтеграціях віджетів

Усі інтеграції, доступні в конструкторі віджетів, підтримують передавання даних віджета в додаткові поля на стороні інтеграції. Для більшості інтеграцій конструктор віджетів може отримати список наявних додаткових полів безпосередньо з інтеграції, щоб ви могли вибрати потрібне поле. Для деяких інтеграцій цей список отримати не можна — потрібно знати ключ цільового поля. Частина з цих інтеграцій усе одно дозволяє створити нове поле безпосередньо в момент підписки, навіть якщо отримати наявний список неможливо.