跳转到主要内容

​
概述

OneSignal + Amazon S3 集成可以自动将存储在您的 S3 存储桶中的 CSV 文件中的自定义事件直接同步到 OneSignal 的自定义事件 API。这使您可以基于存储在数据仓库中的真实用户行为触发自动化 Journey 和个性化消息活动。 您可以同步购买、产品浏览、订阅更改或任何自定义用户操作等事件，以自动触发入门序列、重新参与活动、事务性消息以及跨推送通知、邮件、应用内消息和短信的定向促销。

​
要求

​
OneSignal 要求

  • 自定义事件功能已启用（目前处于测试版 - 请联系 support@onesignal.com）

​
Amazon S3 要求

  • 具有 S3 存储桶访问权限的 AWS 账户
  • 创建角色和策略的 IAM 权限
  • 按照 OneSignal 要求格式化的包含事件数据的 CSV 文件
  • 带有 .csv 扩展名的 UTF-8 编码逗号分隔文件

​
设置

​
准备您的事件 CSV 文件

您的 S3 存储桶必须包含 OneSignal 可以处理的正确格式化的包含事件数据的 CSV 文件： 文件格式要求：
  • 未压缩、UTF-8 编码、带有 .csv 文件扩展名的逗号分隔 CSV 文件
  • 包含标题行（OneSignal 将使用标题作为事件字段名称）
  • 使用字符串 #N/A 表示空值
  • 包含逗号的值应用双引号包裹
  • 包含双引号的值应用第二个双引号转义
文件结构： OneSignal 将每个文件夹路径视为独特的数据源，并将文件名视为该路径内数据的版本。在处理事件时，OneSignal 将始终根据时间戳在选定的文件夹路径中选择最新的数据。 在 S3 中更新事件数据时，您可以替换现有文件或添加更新的版本。OneSignal 将处理新事件并将其发送到自定义事件 API。

​
为 OneSignal 创建 IAM 角色

OneSignal 使用基于角色的身份验证连接到您的 S3 存储桶，遵循 AWS 安全最佳实践。
1

创建 IAM 角色

在您的 AWS 账户中创建一个 IAM 角色，为 OneSignal 的 AWS 账户 ID（341876425553）提供对您 S3 存储桶的只读访问权限：
aws iam create-role \
  --role-name OneSignalS3DataImport \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
      "Action": "sts:AssumeRole"
    }]
  }'
保存返回的角色 ARN，您将在 OneSignal 配置中需要用到它。
2

授予 S3 权限

为您新创建的角色授予对 S3 存储桶的只读访问权限：
aws iam put-role-policy \
  --role-name OneSignalS3DataImport \
  --policy-name OneSignalS3Access \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }]
  }'
将 YOUR_BUCKET_NAME 替换为您实际的 S3 存储桶名称。

​
配置 OneSignal S3 连接

1

转到数据源

在 OneSignal 中，前往 数据 > 集成，然后点击 添加集成。
2

选择 Amazon S3

从可用集成列表中选择 Amazon S3。
3

输入连接详细信息

提供以下信息：
  • 区域： 您的 S3 存储桶区域
  • 存储桶名称： 您的 S3 存储桶名称
  • 角色 ARN： 第 1 步中的 IAM 角色 ARN
  • 前缀： 包含您事件 CSV 文件的文件夹路径（可选）
4

完成安全验证

OneSignal 将生成一个独特的外部 ID 并在下一个屏幕上显示。更新您的 IAM 角色以要求此外部 ID：
aws iam update-assume-role-policy \
  --role-name OneSignalS3DataImport \
  --policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::341876425553:root"},
      "Action": "sts:AssumeRole",
      "Condition": {"StringEquals": {"sts:ExternalId": "GENERATED_EXTERNAL_ID"}}
    }]
  }'
将 GENERATED_EXTERNAL_ID 替换为 OneSignal 仪表板中显示的外部 ID。
5

测试连接

在 OneSignal 中点击测试连接以验证设置是否正常工作。

​
CSV 处理模式

OneSignal 在从您的 S3 存储桶读取事件 CSV 文件时支持两种模式：

​
最新文件模式（默认）

OneSignal 仅处理配置的 S3 前缀和文件夹组中的最新文件。单个文件被解释为要处理的完整事件集。此模式适用于：
  • 单个文件包含某个时间段的所有事件
  • 随时间添加带有更新事件数据的新版本文件
  • 您希望一次处理完整的事件批次

​
合并所有文件模式

OneSignal 获取配置的 S3 前缀和文件夹组中的每个文件，并在处理事件之前将它们合并为单个数据集。此模式适用于：
  • 您的事件数据已分拆成多个文件
  • 您希望处理来自多个源的事件
  • 文件正在以新事件逐步添加
在合并所有文件模式中，所有 CSV 文件必须具有完全相同的列名称和顺序。

​
事件数据映射

连接后，您需要将 CSV 列映射到 OneSignal 自定义事件字段：
1

查看检测的字段

OneSignal 将自动检测您事件 CSV 文件中的列并建议映射。
2

映射必需的事件字段

映射自定义事件的必需字段：
  • 事件名称（必需）：事件的名称/类型
  • 外部 ID（必需）：外部用户 ID
  • 事件时间戳（可选）：事件发生的时间。否则将假定为现在。
3

配置同步设置

设置您的事件处理频率和交付首选项。

​
事件数据映射

将您的 映射到 OneSignal 的自定义事件格式：
OneSignal 字段描述必需
nameevent_name事件标识符是
external_iduser_id用户标识符是
timestampevent_timestamp事件发生时间否
propertiesevent_data否

​
限制

  • SQL 查询： S3 源不支持 SQL 查询或对事件数据的高级转换
  • 文件大小： 单个 CSV 文件不应超过 1GB
  • 更新频率： 最小同步间隔为 15 分钟
  • 文件类型： 仅支持 CSV 文件（不支持 JSON、Parquet 等）

​
FAQ

​
如果我的 CSV 文件有格式错误会发生什么？

OneSignal 将跳过格式错误的行并在集成仪表板中提供详细的错误日志。常见问题包括缺少必需列、无效时间戳格式和不一致的列数。

​
OneSignal 多久检查一次新文件？

OneSignal 根据您配置的同步频率检查您的 S3 存储桶，最小间隔为 15 分钟。

​
需要帮助？

请联系我们的支持团队（support@onesignal.com）或使用应用内聊天获取 S3 集成设置的帮助。