Data Clean Room: работа с источниками

Премиум

Краткий обзор. Настройте источники данных, загружаемые в Data Clean Room (DCR) для дополнения данными атрибуции/внутренними событиями приложения и создания отчетов DCR.

Введение

Многие отчеты DCR предназначены для сопоставления данных атрибуции/внутренних событий приложения с данными из ваших индивидуально настраиваемых источников. Это статья содержит все, что вам нужно знать о настройке индивидуальных источников для использования с DCR, в том числе:

Формат источника

Формат файла

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

  • Должны соответствовать требованиям DCR к именам
  • Формат CSV или GZIP. Файл внутри архива GZIP должен иметь формат CSV.
  • Количество источников данных на папку с данными:
    • CSV: не более 1
    • GZIP: не более 1 цельного файла. Файлы GZIP из нескольких частей поддерживаются при условии следующего именования: имяфайла_part01.gzip, имяфайла_part02.gzip и т. д.

Формат данных

Данные в исходных файлах должны отвечать следующим требованиям:

  • Дата и время:
    • Формат: гггг-мм-дд чч:мм:сс
    • Часовой пояс: UTC
  • Числа: до 2 символов после десятичного разделителя
  • Длина строки: до 256 символов
  • Ограничение по количеству символов:
    • Для имен полей (заголовки столбцов): без пробелов или специальных символов
    • Все прочие данные: без ограничений (все символы действительны)

Создание источника

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

Чтобы создать источник, выполните следующие шаги:

#1: Имя источника

  1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
  2. Нажмите кнопку + New source (Создать источник).
    Откроется страница нового источника.
  3. Введите имя источника в верхнем левом углу.
    • Им может быть любое уникальное имя, которое позволит вам идентифицировать этот источник на платформе DCR. Оно не обязательно должно совпадать с именем файла.
    • Важно! Убедитесь, что имя этого источника отличается от имен других источников в вашем аккаунте, иначе вы не сможете сохранить источник.
    • Требования к названию источника:
      • Длина: от 2 до 80 символов
      • Допустимые символы:
        • буквы (A–Z, a–z)
        • цифры (0-9), не могут быть первым символом имени; 
      • Недопустимые символы:
        • пробелы
        • все остальные символы или специальные символы

#2: Выбор расположения источника

Расположение источника состоит из корзины облачного хранилища (также известной, как коннектор) и дальнейшего пути к папке, по которому DCR читает исходный файл при каждом его обновлении. 

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

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

Если AppsFlyer генерирует папки, единственная необходимая дополнительная информация — это имя, которое вы хотите дать папке источника. (Это папка верхнего уровня, в которой вы обновляете источник каждый раз, когда хотите использовать его для запуска новой версии отчета). Вы также можете указать, хотите ли вы, чтобы папка источника была создана под родительской папкой, часто называемой input.

Чтобы указать расположение источника:

  1. Выберите коннектор, в котором будет (или была) создана папка источника.
    • Если коннекторы в аккаунте не определены, откроется диалоговое окно New connector (Новый коннектор) с предложением создать коннектор.
    • Если у вас уже есть коннекторы, но вы хотите использовать новый, перейдите по ссылке + Новый коннектор.
  2. Введите имя папки источника.
    • По умолчанию отображенное имя папки источника:
      • Основано на имени, которое вы присвоили источнику. Вы можете изменить имя папки в соответствии со своими потребностями согласно требованиям к наименованиям DCR.
      • Указывает, что оно будет сгенерировано в родительской папке под именем input. Эта папка служит родительской папкой для всех источников, загруженных в DCR.
        • Папка input не является обязательной, и вы можете удалить ее или назвать ее по-другому в соответствии с требованиями к наименованиям DCR.
        • Хотя эта папка и не является обязательной, наличие папки input (или аналогичной папки с другим именем) считается правильным вариантом. Такой подход является еще более предпочтительным, если вы используете один коннектор и для загрузки файлов с данными (input), и для получения отчета (output).

 Важно!

Если вы создали путь к папке вручную, убедитесь, что коннектор и путь, которые вы вводите в разделе Расположение источника, соответствуют созданному вручную пути.

#3: Определение структуры источника

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

  • Identifier (Идентификатор). Поле, идентифицирующее уникального пользователя приложения (например, CUID, AppsFlyer ID и др.)
    • Основное назначение идентификаторов в контексте DCR — объединение источников данных для сопоставления соответствующих данных уровня пользователя.
  • Dimension (Параметр). Атрибут, по которому вы классифицируете пользователей приложения (например, гео, дата установки, кампания и др.)
  • Metric (Метрика). Числовые данные, собранные по пользователю приложения (например, доход, количество открытий приложения, LTV и др.)
    • Поле данных, отнесенное к категории метрик, может содержать только числовые значения.

Загрузка макетного файла источника

Для определения структуры источника: 

  • Можно загрузить макетную версию источника из локального файла.
    • Если вы выбираете эту опцию, AppsFlyer всегда автоматически использует путь папки источника.

                                                                - или -

  • Можно загрузить макетную версию источника прямо из его коннектора.
    • Если вы выбираете эту опцию, есть дополнительный вариант:
      • Позволить AppsFlyer автоматически создать структуру папки источника; или
      • Создать структуру папки источника вручную

Чтобы загрузить макетный файл источника, следуйте инструкциям в соответствующей вкладке ниже:

Локальный файл Коннектор (автоматическое создание) Коннектор (создание вручную)
  1. В разделе Структура источника нажмите кнопку DCR_load_fields_from_file.png.
  2. В открывшемся окне выберите Загрузить локальный файл.
  3. Укажите файл CSV или GZIP, который вы хотите загрузить, а затем нажмите ОК.

Определение категории полей

После загрузки файла AppsFlyer анализирует файл, и в списке Доступные поля отображается список всех полей данных (столбцы).

Чтобы определить категории полей:

  1. Выберите одно или несколько полей в левой части списка Доступные поля и с помощью кнопок в центре экрана распределите их по категориям: идентификаторы, параметры или метрики.
    • Когда категория поля определена, оно отображается в списке соответствующей категории в правой части экрана.
    • Чтобы находить нужные поля в списках, можно использовать строку поиска.
    • Чтобы удалить поле из категории, к которой оно было отнесено, выберите его в соответствующем списке категорий и нажмите кнопку Удалить. Поле вернется в список Доступные поля.
  2. Повторяйте этот процесс, пока не присвоите категории всем полям, которые требуется включить в отчеты DCR.
    • Классифицировать все поля в списке доступных полей не требуется. Если же поле будет использоваться в отчете, определять его категорию обязательно.
  3. Если вы редактируете файл источника до сохранения источника и хотите использовать поля из отредактированного файла, перейдите по ссылке Перезагрузить поля в нижней части списка Доступные поля.
    • Обратите внимание, что при перезагрузке источника происходит перезапись имен полей в списке Доступные поля. Все поля, для которых вы ранее определили категории, останутся в списках Идентификаторы, Параметры или Метрики.
    • Если ранее классифицированного поля нет в повторно загруженном файле источника, оно будет отображаться в списке соответствующей категории со значком ошибки.

 Примечание

Если вы решите использовать дополнительные поля из этого источника после его сохранения, это можно сделать, отредактировав структуру источника.

#4: Сохранение источника

Чтобы сохранить источник:
  1. [Необязательно] Нажмите DCR_test_source.png, чтобы проверить ошибки в формате или действительность полей источника.
  2. Нажмите Save (Сохранить), чтобы сохранить источник.

    Источник создан, и на экране появляется сообщение с подтверждением.

    • Если вы загрузили источник из локального файла, сохранение источника запускает автоматическое создание структуры папки, а выведенное на экран сообщение с подтверждением содержит ссылку на папку источника.

    Новый источник отображается в списке всех имеющихся источников во вкладке Источники Data Clean Room.

Загрузка файлов источника для запуска обработки отчета

Каждый раз, когда вы хотите, чтобы AppsFlyer обработал файл источника данных и создал на его основе отчет, вам нужно загрузить новую версию этого файла в папку источника данных внутри серии вложенных подпапок, обозначающих дату и номер версии (плюс одна дополнительная подпапка, сообщающая AppsFlyer, где находятся данные).

AppsFlyer постоянно сканирует новые версии файлов источников для текущей даты и 3 дней до нее. Новая версия отчета запускается каждый раз при обнаружении новой версии файлов источника (включая файлы _SUCCESS, как подробно описано ниже).

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

Ниже приведена структура вложенных подпапок:

  • В каждой папке источника --> 1 подпапка по каждой дате («папка даты»)
    • Формат:dt=гггг-мм-дд/
    • Пример: dt=2022-12-15/
  • В каждой папке даты --> 1 подпапка по каждой версии за эту дату («папка версии»)
    • Формат: v=n/
    • Пример: v=1/
    • Примечание. Папка версии требуется даже в том случае, если вы загружаете файл один раз в день.
  • В каждой папке версии --> 1 подпапка, указывающая расположение данных («папка с данными»)
    • Формат: data/
    • Папка данных — это папка, в которую загружается файл источника.

В большинстве случаев вы будете использовать вызовы API или другие доступные программные средства, чтобы папки даты/версии/данных создавались автоматически при каждой загрузке файла источника данных. Дополнительную информацию см. в документации к API своего облачного сервиса: AWS, GCS.

Файлы _SUCCESS

После загрузки файла источника в папку данных, в папку версии должен быть загружен пустой файл с именем _SUCCESS. Это сигнализирует AppsFlyer о том, что новый файл доступен для обработки. В большинстве случаев для автоматического генерирования этого файла используется скрипт API.

Важно! Файл _SUCCESS необходимо загрузить в папку версии вне папки данных.

Имя файла для файла _SUCCESS:

  • ВСЕ ЗАГЛАВНЫЕ
  • Начинается с нижнего подчеркивания (_)
  • Не имеет расширения файла

Для файлов GZIP из нескольких частей:

  • Загружается только один файл _SUCCESS для всех частей файла.
  • Файл _SUCCESS должен загружаться только по завершении загрузки всех частей файла.

Пример (после загрузки файлов)

После загрузки файлов источников за 2 дня (а также программного создания папок даты/версии/данных и файлов _SUCCESS) структура корзины и папок будет выглядеть следующим образом:

dcr_file_structure_after_uploads.png

Работа с имеющимся источниками

Есть несколько способов работы с имеющимися источниками. Вы запускаете процессы на вкладе Источники в Data Clean Room:

Изменение имени источника

Чтобы изменить имя источника:

  1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
  2. В списке источников наведите курсор на строку с источником, который требуется отредактировать.
  3. Нажмите кнопку «Редактировать» edit_button.png, которая отображается справа от строки.
  4. На странице редактирования источника измените имя источника.
  5. Нажмите кнопку Сохранить, чтобы сохранить источник под новым именем, или Отмена, чтобы отменить изменения.

Редактирование расположения источника

Чтобы изменить расположение источника:

  1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
  2. В списке источников наведите курсор на строку с источником, который требуется отредактировать.
  3. Нажмите кнопку «Редактировать» edit_button.png, которая отображается справа от строки.
  4. Прокрутите страницу редактирования источника вниз до раздела Source location (Расположение источника).
  5. Нажмите кнопку «Редактировать» edit_button.png рядом с текущим расположением источника.
  6. Внесите необходимые изменения в диалоговом окне Расположение источника и формат.
  7. Нажмите Apply (Применить), чтобы применить изменения.
  8. Нажмите кнопку Сохранить, чтобы сохранить источник в новом месте/формате, или Отмена, чтобы отменить изменения.

При редактировании расположения источника AppsFlyer создает на коннекторе папку с новым именем.

  • AppsFlyer ищет последующие версии файла источника и сопутствующие файлы _SUCCESS в новой папке.
  • Все версии файла источника, которые были загружены до изменения имени, останутся в прежней папке файла источника.

Изменение структуры источника

Чтобы изменить структуру источника:

  1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
  2. В списке источников наведите курсор на строку с источником, который требуется отредактировать.
  3. Нажмите кнопку «Редактировать» edit_button.png, которая отображается справа от строки.
  4. На странице редактирования источника поля, ранее классифицированные как идентификаторы, параметры и метрики, будут отображаться в списках соответствующих категорий в правой части экрана.
  5. Вы можете перенести поле из одной категории в другую без повторной загрузки полей из файла источника. Для этого:
    1. Сначала выберите его в списке соответствующей категории и нажмите кнопку Remove (Удалить), чтобы оно вернулось в список доступных полей.
    2. Затем выберите его в списке доступных полей и с помощью кнопок в центре экрана определите его категорию: идентификатор, параметр или метрика.
  6. Чтобы работать с полями из файла источника, не отнесенными к категориям, их нужно повторно загрузить из расположения источника или из локального файла. Сделайте этот выбор, нажав соответствующую ссылку Перезагрузить поля в нижней части списка Доступные поля.
  7. AppsFlyer проанализирует файл, и все поля данных (столбцы) без категорий появятся в списке доступных полей.
    • Поля, уже классифицированные как идентификаторы, параметры и метрики, по прежнему будут отображаться в списках соответствующих категорий в правой части экрана.
    • Если ранее классифицированного поля нет в повторно загруженном файле источника, оно будет отображаться в списке соответствующей категории со значком ошибки.
  8. Выберите одно или несколько полей в левой части списка Доступные поля и с помощью кнопок в центре экрана распределите их по категориям: идентификаторы, параметры или метрики.
  9. Когда все необходимые изменения будут внесены, нажмите кнопку Сохранить, чтобы сохранить источник с обновленной структурой, или Отменить, чтобы сбросить внесенные изменения.

 Важно!

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

  • Удаленные поля, поля без категории и поля, категория которых изменилась, автоматически исключаются изо всех отчетов, в которых они использовались.
  • Вновь добавленные поля или поля с определенной категорией не будут включены в имеющиеся отчеты автоматически, пока вы не добавите их в определения отчетов.

Удаление источника

  1. Перейдите на вкладку Sources (Источники) в Data Clean Room.
  2. В списке источников наведите курсор на строку с источником, который вы хотите удалить.
  3. Нажмите кнопку «Удалить» delete_button.png, которая отображается справа от строки.
  4. В диалоговом окне подтвердите удаление источника.
    • Нельзя удалить источник, который используется в отчете. Если вы попробуете это сделать, в сообщении будет указан список отчетов, в которых задействован данный источник. Чтобы удалить такой источник, вы можете выполнить одно из следующих действий:
      • Удалить отчеты, в которых он используется.
      • Удалить поля источника из определений отчетов, в которых он используется.