# Экспорт сырых данных

Этот документ описывает, как интерпретировать и анализировать сырые данные, экспортируемые из Gravity Field. Включены рекомендации по работе с полями, обработке ошибок, сбору данных по экспериментам и связыванию событий с тестами.

# 📥 Как получить выгрузку сырых данных

Сырые данные Gravity Field доступны по адресу: 👉 https://s3.gravityfield.ai/

# 🔐 Доступ

Данные для авторизации можно получить у команды, сопровождающей ваш проект, или обратившись в службу поддержки Gravity Field.

# ⚙️ Способы доступа

Вы можете получить программный доступ к файлам двумя способами:

MinIO Client Кросс-платформенный инструмент для работы с S3-хранилищами 🔗 https://min.io/download

MinIO API и SDK Поддерживает интеграции с различными языками программирования 🔗 https://min.io/docs/minio/linux/developers/minio-drivers.html

# 🗂️ Структура выгрузок

Данные выгружаются по запросу за указанный период. Для каждого дня создаётся отдельный CSV-файл (текстовый файл, разделённый запятыми).

Разовые выгрузки попадают в папку: /[section_id]/batch_data/

Ежедневные выгрузки по расписанию размещаются в: /[section_id]/daily_data/

[section_id] — уникальный идентификатор вашей секции/проекта в системе Gravity Field.

# ⏳ Срок хранения данных

Ежедневные выгрузки: хранятся 7 дней. При поступлении новых данных автоматически удаляются файлы, которым более 7 дней.

Разовые выгрузки: также удаляются через 7 дней после создания.

Дата выгрузки соответствует дате создания файла в хранилище и может быть определена по метаданным.

# 📁 Формат файлов

Файлы содержат события в формате CSV. Каждая строка — одно событие. Поля разделены запятой ,.

# ⚠️ Вложенные структуры

Некоторые поля содержат вложенные данные — списки или JSON-объекты. Они также используют запятую как разделитель, что может вызвать ошибки при импорте в Excel или BI-инструменты.

# 📦 Структура данных

Каждый CSV-файл содержит строки-события, зафиксированные системой персонализации Gravity Field. Одна строка — одно событие.

Каждая строка файла представляет одно событие, одно из следующих типов:

• Page View — просмотр страницы
• Event Hit — событие (например, "добавление в корзину")
• Variation Impression — показ вариации в эксперименте
• Variation Click — клик по вариации
• Widget Impression — показ рекомендательного блока
• Product Impression — показ товара
• Product Click — клик по товару
• Visible Impression — элемент попал во viewport пользователя

# 📋 Основные поля

# 🔢 Значения поля type

Поле type — это числовой идентификатор типа события.
Значения и соответствия приведены ниже:

# ⚙️ Особенности обработки данных

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

# 🔄 1. Повторяющиеся и пустые значения

• Некоторые поля (например, campaignId, experienceId, variationId) могут быть пустыми:

  • Это нормально для событий, не относящихся к экспериментам (type ≠ 2, 3).
  • Значения 000000000000000000000000 также интерпретируются как «не применимо».

• У одного пользователя (uid) или в рамках одной сессии (sessionId) может быть несколько событий одного типа — это ожидаемо.

# 📉 2. eventValue = 0 — не всегда ошибка

Поле eventValue отражает числовую ценность события (например, сумму покупки), только если событие имеет тип 1 (Event Hit).

Значение 0 может быть корректным в следующих случаях:

• Тип события — не Event Hit (например, Page View, Variation Impression)
• Event Hit, но событие не связано с ценностью (например, scroll, search, click)
• Отсутствие передачи стоимости в течение определённого периода:

👉 Чтобы убедиться, что eventValue = 0 допустим — проверьте поле eventProperties. Если там есть "value": 0, то значение передано осознанно.

# 👤 3. Как объединять события по пользователю и сессии

Поскольку все взаимодействия пользователя с сайтом и приложением отправляются в Gravity Field отдельными строками, для корректного анализа необходимо учитывать:

• Для получения полного списка событий пользователя — фильтруйте данные по колонке uid
• Для получения событий в рамках одной сессии — используйте одновременную фильтрацию по uid и sessionId

Это особенно важно при анализе поведения, воронок и при расчёте эффективности кампаний с атрибуцией по сессии.

# 🧪 4. Связь с экспериментами

• События типа Event Hit не содержат напрямую полей campaignId, experienceId, variationId
• Чтобы связать событие с экспериментом, необходимо использовать sessionId:
  1. Найти Variation Impression с нужным variationId
  2. Зафиксировать sessionId
  3. Найти события Event Hit с тем же sessionId, произошедшие позже
• Такой подход требует корректного учета времени события (moscowTime) и последовательности событий в сессии

# 🛠 5. Проблемы при импорте CSV

• Вложенные поля (eventProperties, audiences, eventCart) содержат JSON-объекты или списки, где также используется запятая ,
• Это может привести к некорректному разбору CSV в Excel или BI-инструментах

Рекомендации:

• Использовать экранирование (кавычки "...") при чтении
• Или менять разделитель столбцов на ;
• Для анализа — использовать парсеры, поддерживающие вложенные структуры (pandas, csv.DictReader, и др.)

# ⏳ 6. Срок хранения данных

• По умолчанию файлы хранятся 7 дней
• После этого они удаляются автоматически, даже если были скачаны не полностью
• Для разовых выгрузок или продления срока — обратитесь в поддержку

# 🔄 7. Несколько вариаций в одной сессии

В рамках одной сессии (sessionId) пользователь может увидеть несколько вариаций разных экспериментов. Это влияет на интерпретацию данных:

• Необходимо учитывать только те события, которые произошли после нужного показа вариации
• Для повышения чистоты эксперимента:
  • Исключайте сессии с множественными вариациями
  • Или учитывайте логику последнего показа

# 🎯 8. Учет атрибуции кампании

При анализе эффективности кампаний необходимо учитывать тип атрибуции, заданный в настройках: по пользователю, по сессии, по клику или по кастомному событию. Также важно учитывать клейкость вариации (по сессии или по пользователю).

Дополнительно см. статью:
👉 Атрибуция кампаний в Gravity Field

# ✅ Рекомендации по работе с данными

• Используйте uid для получения полной истории действий пользователя
• Используйте sessionId для анализа действий в рамках одной сессии
• Учитывайте тип события (type) — не все поля применимы ко всем типам
• Работайте с eventValue только для событий типа Event Hit
• Учитывайте временной порядок событий (moscowTime) при анализе последовательности действий
• Для анализа экспериментов:
  • фиксируйте variationId и извлекайте sessionId из Variation Impression
  • находите соответствующие Event Hit по sessionId
  • учитывайте только события, произошедшие после показа
• Проверяйте настройки атрибуции кампании (по сессии, пользователю, клику и т.д.):👉 Атрибуция кампаний
• Фиксируйте период анализа в рамках дат теста
• При необходимости — используйте экранирование или альтернативный разделитель для корректной обработки CSV