跳转到主要内容

概述

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 集成设置的帮助。
I