Data Locker — коннектор для доставки данных

Краткий обзор. Data Locker записывает сырые данные в облачное хранилище практически в реальном времени (задержка составляет около 6 часов). Данные могут записываться либо в корзину AWS AppsFlyer, либо в вашу корзину AWS или GCS

6133_Data_Locker_-_your_bucket.png

Data Locker

Основные функции Data Locker

  • Приложения: поддерживает несколько приложений, которые добавляются автоматически
  • Надежность: данные хранятся в выбранном вами облачном хранилище (корзине).
  • Гибкость: вы можете выбрать, какие данные включать.
  • Детализация: данные разбиты по типам отчетов, дням и часам
  • Доступность: извлечение данных по мере необходимости
  • Актуальность данных: 6-часовая задержка или ежедневное обновление в зависимости от типа отчета.  Время задержки одинаковое (6 часов) независимо от часового пояса приложения. 
  • Владелец корзины:
    • Получение данных через корзину AWS, принадлежащую AppsFlyer. Срок хранения данных: 30 дней.
    • Получение данных через поставщика облачных услуг в ваше хранилище. Срок хранения данных: устанавливаете вы. 

Отчеты, доступные в Data Locker

Основные отчеты по атрибуции: UA и ретаргетинг
Категория Тип отчета (тема) Актуальность данных* Органические/Неорганические Уникальные возможности Data Locker
Привлечение пользователей Clicks (Клики) 6-часовая задержка
Ретаргетинг Clicks (Клики) 6-часовая задержка
Привлечение пользователей Показы 6-часовая задержка
Ретаргетинг Показы 6-часовая задержка
Привлечение пользователей Установки 6-часовая задержка Оба  
Привлечение пользователей In-App Events (Внутренние события приложения)  6-часовая задержка Оба  
Привлечение пользователей Атрибутированный доход от рекламы Ежедневно + 2 Неорганические  
Привлечение пользователей Органический доход от рекламы Ежедневно + 2 Органика  
Ретаргетинг Доход от рекламы ретаргетинга Ежедневно + 2 Неорганические  
Ретаргетинг Конверсии 6-часовая задержка Неорганические  
Ретаргетинг Внутренние события приложений 6-часовая задержка Неорганические  
Ретаргетинг Sessions (Сеансы) 6-часовая задержка Оба
Привлечение пользователей Sessions (Сеансы) 6-часовая задержка Оба
Привлечение пользователей Удаления Ежедневно (удаления) Неорганические  
Привлечение пользователей Органические удаления Ежедневно (удаления) Органика  
Повторные установки Повторные установки 6-часовая задержка Неорганические  
Повторные установки Органические повторные установки 6-часовая задержка Органика  
Protect360
Тип отчета (тема) Актуальность данных*
Заблокированные установки 6-часовая задержка
Заблокированные события 6-часовая задержка
Заблокированные клики 6-часовая задержка
[AG*] Post-attribution installs (Установки после атрибуции) Ежедневно
SKAdNetwork
Обновление данных: ежедневно 
Тип отчета (тема)
[FF*] Postbacks (Постбэки)
[FF*] Installs (Установки)
[FF*] Redownloads (Повторные загрузки)
[FF*] In-app events (Внутренние события)
Атрибуция People-Based
Обновление данных: ежедневно
Тип отчета (тема)
[FF*] Website visits (Посещения сайта)
[FF*] Website events (События на сайте)
[FF*] Website-assisted installs (Установки, дополнительным источником которых является сайт)
[FF*] Conversion Paths (Пути конверсии)
Расшифровка сокращений

* Расшифровка сокращений

[FF] Поля отчета зафиксированы Appsflyer. Они не связаны с полями, которые можно выбирать для отчетов.

[AG] Прозрачность агентств не поддерживается.

6-часовая задержка: Данные разделены на папки по часу прибытия. Это час, когда событие было помещено в Data Locker. Папки Data Locker записываются в течение шести часов после фактического времени события для событий в реальном времени. Для каждого часа дня имеется папка, всего 24, от 0 до 23, и дополнительная папка для данных, которые поступают с опозданием. Время задержки одинаковое (6 часов), независимо от часового пояса приложения.

Ежедневно: отчеты записываются в папку h=23. Такие отчеты обычно доступны с 10:00–12:00 UTC в папке h=23 за предыдущий день. Например, отчет по данным за понедельник находится в папке Monday H=23. Данные доступны с 10:00 UTC вторника. 

Ежедневно (удаления): такие отчеты подготавливаются ежедневно; они обычно доступны с 10:00–12:00 UTC и чаще всего записываются в папку h=2. То есть в папке h=2 содержатся отчеты по удалениям за предыдущий день. Однако данные могут быть записаны в более позднюю папку. Поэтому в вашем процессе импорта должны читаться данные из всех папок h1-h=24 и h=late (последняя) в теме удалений. Например, отчет по данным за понедельник находится в папке вторника Tuesday h=2. Данные доступны с 10:00 UTC вторника. 

Ежедневно+2: Данные о доходах от рекламы будут доступны через 2 дня, то есть данные, сгенерированные в понедельник, появятся в папке Monday H=23 в среду после 06:00 UTC.

Архитектура Data Locker

В вашем хранилище данных (корзине) данные упорядочены по типу отчета. Данные этого отчета хранятся в его папке, разделенной на запись данных и часы, как показано на рисунке ниже. 

DataLockerFileStructure.png

Структура папок Data Locker:  <cloud service repository>/data-locker-hourly/t=<report type>/dt=<date YYYY-MM-DD>/h=<Hour h где:

  • <cloud service repository> — имя вашей корзины <bucket> и папки <folder>. 
    • Имя корзины в хранилище AppsFlyer: ext-reports, папка настраивается для каждого аккаунта и отображается на странице настроек. 
    • Если используется ваша корзина, имя хранилища выглядит как «af-datalocker-имя вашей папки». 
  • <t=report type> — тип отчета, находящегося в папке.
  • <dt= folder date> — дата записи данных в формате гггг-мм-дд.
  • <h=hours> — время (час) записи данных. Почасовых папок может быть до 25. Эти папки показывают время получения данных о событии, а не время самого события. Папки называются h=0, h=1, h=2... до h=23 и h=late (поздние). Например, папка h=0 содержит события, полученные с 00:00 до 01:00 UTC, а папка h=20 содержит события, полученные с 20:00 до 21:00. Для отчетов, которые записываются раз в день, существует только одна папка h=23.
  • В каждой папке:

    • Данные могут быть разбиты на несколько файлов, чтобы избежать образования больших файлов. Файлы называются part-00000, part-00001, part-00002 и так далее. В папке может быть до 1000 файлов. Мы можем увеличить максимальное количество файлов в будущем без предварительного уведомления.

    • Последний записываемый файл в каждой папке — это пустой файл с именем _SUCCESS. Этот файл является индикатором, указывающим на то, что в папку больше не будет записываться никаких данных. Поэтому не просматривайте данные в папке, пока не убедитесь, что  в ней есть файл  _SUCCESS.Примечание: Файл _SUCCESS появляется и в тех случаях, когда данных для записи в папку нет.

  • Папка "Поздние события"

    • Последняя папка содержит события за предыдущий день, которые поступили после полуночи (другими словами, события, которые поступили с 00:00 до 02:00 UTC следующего дня). Например, пользователь устанавливает приложение в понедельник в 08:00, событие поступает во вторник в 01:00. Событие записывается в последнюю папку понедельника (Monday).

    • В папке также есть флаг _SUCCESS, как описано в предыдущем разделе.

    • Данные в последней папке не записываются ни в какую другую папку.

    • Автоматизированные процессы должны искать данные в последней папке таким же образом, как и в других папках. 

  • Папка _temporary (временная)
    • В некоторых случаях мы создаем в папке h временную папку. Проигнорируйте временную папку и вложенные в нее папки.  Например: /t=impressions/dt=2021-04-11/h=18/_temporary.

Структура и формат файла

  • Файлы Data Locker основаны на отчетах по необработанным данным V5 (см. Raw Data Reports V5).
  • Фактический файл данных имеет формат CSV, но не имеет расширения файла.
  • Файлы отчета заархивированы в .gz .
  • Каждый файл имеет строку заголовка.
  • Значения, которые содержат запятую, заключаются в двойные кавычки ("), к примеру "iPhone6,1".

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

Вы можете использовать данные из отчетов и добавлять их в свои базы данных. Чтобы извлечь данные и добавить их в ваши базы данных, вам необходимо знать формат отчета. Отчеты Data Locker основаны на отчетах по сырым данным. Тем не менее, окончательный формат отчета зависит от полей, которые вы решите включить.

Некоторые поля пусты или имеют значение null. Это говорит об отсутствии данных для предоставления в контексте этого отчета. Как правило, null означает, что соответствующее поле не заполняется в контексте отчета и типа приложения. Пустое значение "" означает, что поле актуально в этом контексте, но данные для его заполнения не найдены.

Часовой пояс и валюта

Настройки часового пояса и валюты для приложения не влияют на данные в Data Locker.

  • Часовой пояс: в отчетах Data Locker используется часовой пояс UTC
  • Валюта: поле event_revenue_usd в долларах США.

Корзина AppsFlyer vs. Клиентская корзина (AWS или GCS)

 Внимание!

Если вы используете вариант с клиентской корзиной: 

  • Убедитесь, что вы соответствуете требованиям законов о защите данных, таких как GDPR, и политикам рекламных сетей / SRN в отношении хранения данных.
  • Не используйте вариант с клиентской корзиной для отправки данных третьим лицам. 
  • Вы выбираете, кому принадлежит корзина, в которую будут записываться данные:
    • Корзина AppsFlyer
    • Клиентская корзина — AWS или GCS
  • Изменить этот выбор можно в любой момент:
      • Переход с корзины AppsFlyer на корзину клиента выполняется в пользовательском интерфейсе. Изменение вступает в силу в течение одного часа. Это значит, что мы перестаем записывать данные в текущую корзину и начинаем записывать их во вновь выбранную. 
      • Если вы хотите прекратить использование своей клиентской корзины, выберите корзину AppsFlyer. 
  Корзина AppsFlyer (AWS)  Клиентская корзина (AWS) Клиентская корзина (GCS)
Название корзины Задается AppsFlyer.

Задается вами. Должно содержать префикс "af-datalocker-".

Пример: af-datalocker-your-bucket-name

Нет ограничений

Владелец корзины AppsFlyer Клиент Клиент
Поддерживаемая платформа хранения AWS AWS  GCS
Учетные данные для вашего доступа к данным Доступны администратору в пользовательском интерфейсе Data Locker Не известны AppsFlyer. Используйте свои учетные данные для AWS. Не известны AppsFlyer. Используйте свои учетные данные для GCS.
Хранение данных Данные удаляются через 30 дней. Ваша ответственность Ваша ответственность
Запросы на удаление данных Ответственность AppsFlyer Ваша ответственность Ваша ответственность
безопасность Корзиной управляет AppsFlyer. У клиента есть доступ для чтения. Корзиной управляет клиент. По этой корзине AppsFlyer требуются разрешения GetObject, ListBucket, DeleteObject, PutObject. Корзина должна быть выделена для использования AppsFlyer. Не используйте ее для других целей. Корзиной управляет клиент. Для AppsFlyer требуются разрешения, указанные в статье Настройка GCS. Корзина должна быть выделена для использования AppsFlyer. Не задействуйте ее для других целей.
Место в хранилище Управляется AppsFlyer Управляется вами Управляется вами
Контроль доступа с помощью конечных точек VPC с политиками корзины Не применимо [Необязательно] Если вы реализуете безопасность конечных точек VPC на уровне корзины в AWS, необходимо внести серверы AppsFlyer в разрешенный список.

Процедура

Настройте Data Locker

Используйте эту процедуру для настройки Data Locker. Изменения в настройках Data Locker и последующие изменения вступают в силу в течение 3 часов. 

Необходимое условие для настройки клиентской корзины AWS:

Если вы настраиваете Data Locker, используя свою клиентскую корзину AWS (то есть корзину, владельцем которой являетесь вы), сначала нужно завершить настройку вашей корзины AWS S3.

AppsFlyerAdmin_us-en.png Чтобы настроить Data Locker:

  1. Настройку выполняет администратор. 
  2. В AppsFlyer перейдите в раздел  Integration (Интеграция) > Data Locker. 
  3. Выберите способ интеграции с Amazon S3. Выберите один из следующих вариантов
    • Корзина AWS AppsFlyer. Переходите к шагу 4. 
    • Корзина AWS клиента.
      1. Введите название своей корзины AWS. Без префикса af-datalocker-
      2. Нажмите Test (Тестировать).
      3. Убедитесь в отсутствии сообщения об ошибке, указывающей на неверный путь к корзине.
  4. Выберите одно, несколько или все приложения. Выберите все, чтобы автоматически включать приложения, которые вы добавите в будущем.
  5. Нажмите Применить.
  6. [необязательно] Медиа-источники. Выберите один или несколько медиа-источников для включения в отчеты.
    • По умолчанию = Все. То есть медиа-источники, которые будут добавлены в будущем, добавляются автоматически.
  7. Выберите один или несколько типов отчетов.
  8. [необязательно] Внутренние события. Укажите внутренние события приложения, которые необходимо добавить. Если типов внутренних событий более 100, вы не сможете воспользоваться поиском. Чтобы выбрать события, введите их точные имена. 
    • По умолчанию = Все. То есть внутренние события, которые будут добавлены в будущем, добавляются автоматически.
  9. Нажмите Применить.
  10. [опционально] Поля (по умолчанию = Все):   Выберите поля, которые хотите видеть в отчете. Примечание: Мы добавляем поля время от времени, учтите это при импорте данных.
  11. Нажмите кнопку Save Configuration (Сохранить настройки). Возможна одна из следующих ситуаций:
    • Если вы выбрали корзину AWS AppsFLyer:
      • Создается специальная корзина AWS. Отображаются учетные данные корзины.
      • Корзина доступна только с использованием учетных данных клиента. С вашими учетными данными вы получаете доступ к корзине только для чтения.
    • Если вы выбрали Корзину AWS клиента:
      • Данные начнут записываться в вашу корзину AWS в течение 3 часов.

Настройка Data Locker: ваша корзина AWS S3

Процедуру, описанную в этом разделе, должен выполнить ваш администратор AWS.

Вы можете удалить файлы из Data Locker через 25 и более часов после их записи. Не удаляйте файлы до истечения этого времени. 

Справочная информация для администратора AWS: 

  • AppsFlyer записывает ваши данные в принадлежащую вам корзину S3. Чтобы использовать этот метод, необходимо выполнить следующее:
    • Создайте корзину с именем af-datalocker-моякорзина. Префикс "af-datalocker-" обязателен. Вместо заполнителя "моякорзина" можно указать любое текстовое значение.
  • Рекомендуем использовать формат "af-datalocker-гггг-мм-дд-чч-мм-произвольный-текст". Где "гггг-мм-дд-чч-мм" — это текущие дата и время, а "произвольный-текст" — нужное вам название, как показано на следующем рисунке.
    Пользовательский интерфейс в консоли AWS

    MyBucket.jpg

  • Когда корзина создана, предоставьте AppsFlyer необходимые разрешения, используя следующую процедуру. 

Чтобы создать корзину и предоставить разрешения AppsFlyer: 

  1. Войдите в консоль AWS.
  2. Откройте сервис S3.
  3. Чтобы создать корзину:
    1. Нажмите Create bucket (Создать корзину).
    2. Заполните поле Bucket name (Название корзины) следующим образом: начните с префикса af-datalocker-, затем добавьте оставшуюся часть, как описано выше.
    3. Нажмите Создать корзину.
  4. Чтобы предоставить разрешения AppsFlyer:
    1. Выберите корзину. 
    2. Перейдите на вкладку Permissions (Разрешения). 
    3. В разделе Bucket policy (Политика корзины) нажмите Edit (Редактировать). 
      Откроется окно политики корзины.
    4. Вставьте в это окно следующий фрагмент кода.
      {
        "Version": "2012-10-17",
        "Statement": [
          {
            "Sid": "AF_DataLocker_Direct",
            "Effect": "Allow",
            "Principal": {
              "AWS": "arn:aws:iam::195229424603:user/product=datalocker__envtype=prod__ns=default"
            },
            "Action": [
              "s3:GetObject",
              "s3:ListBucket",
              "s3:DeleteObject",
              "s3:PutObject"
            ],
            "Resource": [
              "arn:aws:s3:::af-datalocker-my-bucket",
              "arn:aws:s3:::af-datalocker-my-bucket/*"
            ]
          }
        ]
      }
      
  5. В этом коде замените af-data-locker-my-bucket на название созданной вами корзины.

  6. Выберите Сохранить изменения.

  7. Выполните процедуру настройки Data Locker.

Сброс учетных данных

Администратор может сбросить учетные данные корзины AppsFlyer в любое время. Внимание! Если вы сбрасываете учетные данные, необходимо обновить учетные данные в сценариях импорта данных.

AppsFlyerAdmin_us-en.png Чтобы сбросить учетные данные:

  1. В AppsFlyer перейдите в раздел  Integration (Интеграция) > Data Locker. 
  2. В разделе учетных данных нажмите Reset credentials (Сбросить учетные данные).
    Откроется окно подтверждения.
  3. Нажмите Reset (Сбросить).
  4. Подождите (около 20 секунд), пока появится сообщение Credentials successfully reset (Учетные данные успешно сброшены).
    Доступны обновленные учетные данные.

Извлечение данных

Используйте предпочитаемый инструмент извлечения данных S3, AWS CLI или один из инструментов, описанных в следующих разделах.

AWS CLI

Прежде чем начать:

  • Установите AWS CLI на ваш компьютер.
  • В AppsFlyer перейдите в Data Locker и получите информацию, содержащуюся на панели учетных данных, так как она необходима для выполнения этой процедуры. 

Чтобы использовать AWS CLI:

  1. Откройте терминал. Для этого в Windows (<Windows> + <R>), нажмите OK.
    Откроется окно командной строки.
  2. Введите aws configure
  3. Введите ключ доступа AWS, как он отображается на панели учетных данных.
  4. Введите ваш ключ доступа AWS, как он отображается на панели учетных данных.
  5. Введите eu-west-1
  6. Нажмите Enter (нет)

Используйте указанные команды CLI по мере необходимости.

В следующих командах можно найти значение {home-folder}

Чтобы перечислить папки в вашей корзине

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/

Список файлов и папок

В вашей корзине Data Locker есть три типа папок:

  • Тип отчета t=
  • Дата dt=
  • Час h=

Чтобы вывести список всех отчетов определенного типа:

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/t=installs/

Чтобы вывести список всех отчетов определенного типа за определенный день:

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/t=installs/dt=2019-01-17

Чтобы вывести список всех отчетов определенного типа за определенный час определенного дня:

aws s3 ls s3://af-ext-reports/{home-folder}/data-locker-hourly/t=installs/dt=2019-01-17/h=23

Чтобы скачать файлы за определенную дату:

aws s3 cp s3://af-ext-reports/<home-folder>/data-locker-hourly/t=installs/dt=2020-08-01/h=9/part-00000.gz ~/Downloads/

Cyberduck

Прежде чем начать:

  • Установите клиент Cyberduck.
  • В AppsFlyer перейдите в Data Locker и получите информацию, содержащуюся на панели учетных данных. Эта информация потребуется вам для настройки Cyberduck. 

Чтобы настроить Cyberduck:

  1. В Cyberduck нажмите Action (Действие).
  2. Выберите Новая закладка. Откроется окно.
  3. В первом поле (помечено [1] на следующем снимке экрана) выберите Amazon S3.

    DataDuckSmall2.png

  4. Заполните поля следующим образом:
    • Nickname:произвольный текст
    • Server:  s3.amazonaws.com
    • Access Key ID: скопируйте ключ доступа AWS, как он отображается на панели учетных данных в AppsFlyer.
    • Secret Access Key: скопируйте секретный ключ доступа к корзине, как он отображается на панели учетных данных в AppsFlyer.
    • Путь: {Bucket Name}/{Home Folder} Например: af-ext-reports/1234-abc-ffffffff
  5. Чтобы закрыть окно, нажмите Х в верхнем правом углу.
  6. Выберите соединение.
    Отобразятся каталоги данных.

Браузер Amazon S3

Прежде чем начать:

  • Установите браузер Amazon S3.
  • В AppsFlyer перейдите в Data Locker и получите информацию, содержащуюся на панели учетных данных, так как она необходима для выполнения этой процедуры. 

Чтобы настроить браузер Amazon S3:

  1. В браузере S3 нажмите Accounts (Аккаунты) > Add New Account (Добавить новый аккаунт).
    Откроется окно Add New Account (Добавить новый аккаунт).

    mceclip0.png

  2. Заполните поля следующим образом:
    • Account Name (Имя учетной записи): произвольный текст. 
    • Access Key ID:скопируйте ключ доступа AWS, как он отображается на панели учетных данных в AppsFlyer. 
    • Secret Access Key:скопируйте секретный ключ доступа к корзине, как он отображается на панели учетных данных в AppsFlyer.
    • Выберите Encrypt Access Keys с помощью пароля и введите пароль. Запишите этот пароль.
    • Выберите Use secure transfer. 
  3.  Нажмите Save changes.
  4. Нажмите Buckets (Корзины) > Add External Bucket (Добавить внешнюю корзину).
    Откроется окно Add External Bucket (Добавить внешнюю корзину).

    mceclip2.png

  5. Введите Bucket name.Имя корзины имеет следующий формат: {Bucket Name}/{Home Folder}. Значения, необходимые для имени корзины и домашней папки, появятся в окне учетных данных. 
  6. Нажмите Add External bucket.Корзина создана и отображается на левой панели окна.
    Теперь вы можете получить доступ к файлам Data Locker. 

Дополнительные сведения

Ограничения и особенности

Особенности
Специфика Заметки 
Рекламным сетям Не для использования в рекламных сетях. 
Агентства Не для использования агентствами
Часовой пояс приложения Не применимо Папки хранилища данных разделены по часам с использованием часового пояса UTC. Фактические события содержат время в формате UTC. При необходимости переводите время в любой другой часовой пояс. Независимо от часового пояса вашего приложения, задержка от возникновения события до момента его записи в Data Locker остается неизменной, то есть 6 часов. 
Валюта приложения  Не поддерживается
Ограничения на размер Не применимо
Актуальность данных Файлы обновляются ежечасно с задержкой в шесть часов от времени события.
Исторические данные Не поддерживается. Данные о событиях отправляются после настройки Data Locker. Если вам нужны исторические данные, используйте Pull API.
Доступ члена команды Члены команды не могут настроить Data Locker. 
Одно приложение/Несколько приложений Поддержка нескольких приложений. Data Locker на уровне аккаунта.

Примечания для разработчиков

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

  • Временная папка:
    • В некоторых случах временная папка остается. Не обращайте внимания на эту папку.   Пример: /data-locker-hourly/t=inapps/dt=2020-11-13/h=2/_temporarary/0/_temporary/.
    • Используйте только те папки, которые отмечены флагом _SUCCESS
  • Последовательность столбцов в отчетах: 
    • Последовательность полей в отчетах всегда одинакова. При добавлении новых полей, они появляются справа от существующих. Список полей в пользовательском интерфейсе упорядочен таким же образом.

Устранение неполадок

  • Симптом: Невозможно получить данные с помощью интерфейса командной строки AWS
  • Сообщение об ошибке: Произошла ошибка (AccessDenied) при вызове операции ListObjectsV2: доступ запрещен
  • Причина: Используемые учетные данные AWS не соответствуют учетным данным для корзины AppsFlyer. Это может быть вызвано наличием нескольких или неверных учетных данных на вашем компьютере. 
  • Решение:
    1. Используйте другой инструмент, например, Cyberduck, чтобы получить доступ к корзине, то есть не интерфейс командной строки (CLI). Сделайте это, чтобы убедиться, что используемые учетные данные работают. Если вы можете подключиться с помощью Cyberduck, это указывает на проблему с кэшем учетных данных. 
    2. Обновите кэш учетных данных AWS.
      Скриншот из AWSmceclip0.png 
Была ли эта статья полезной?