> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Amazon S3
> Amazon S3 CSV 파일에서 OneSignal로 사용자 지정 이벤트를 동기화하여 사용자 행동을 기반으로 자동화된 Journey 및 개인화된 메시징 캠페인을 트리거합니다.
export const PLATFORM_0 = "S3 CSV"
export const DATA_TYPE_0 = "file columns"
export const COLUMN_HEADER_0 = "CSV Column Example"
export const PROPERTIES_DESCRIPTION_0 = "Event properties as JSON string"
## 개요
OneSignal + Amazon S3 통합을 사용하면 S3 버킷에 저장된 CSV 파일에서 OneSignal의 Custom Events API로 직접 사용자 지정 이벤트를 자동으로 동기화할 수 있습니다. 이를 통해 데이터 웨어하우스에 저장된 실제 사용자 행동을 기반으로 자동화된 Journey 및 개인화된 메시징 캠페인을 트리거할 수 있습니다.
구매, 제품 보기, 구독 변경 또는 사용자 지정 사용자 액션과 같은 이벤트를 동기화하여 푸시 알림, Email, In-App Message 및 SMS 전반에 걸쳐 온보딩 시퀀스, 재참여 캠페인, 트랜잭션 메시지 및 타겟 프로모션을 자동으로 트리거할 수 있습니다.
***
## 요구 사항
### OneSignal
* **Custom Events** 기능이 활성화됨 (현재 베타 - `support@onesignal.com`에 문의)
### Amazon S3
* S3 버킷 액세스 권한이 있는 **AWS 계정**
* 역할 및 정책을 생성할 수 있는 **IAM 권한**
* OneSignal 요구 사항에 따라 형식이 지정된 이벤트 데이터가 있는 **CSV 파일**
* `.csv` 확장자가 있는 **UTF-8로 인코딩된** 쉼표로 구분된 파일
***
## 설정
### 이벤트 CSV 파일 준비
S3 버킷에는 OneSignal이 처리할 수 있는 적절하게 형식이 지정된 이벤트 데이터가 있는 CSV 파일이 포함되어야 합니다:
**파일 형식 요구 사항:**
* `.csv` 파일 확장자가 있는 압축되지 않은 UTF-8로 인코딩된 쉼표로 구분된 CSV
* 헤더 행 포함 (OneSignal은 헤더를 이벤트 필드 이름으로 사용합니다)
* null 값은 문자열 `#N/A`로 표현
* 쉼표가 포함된 값은 큰따옴표로 래핑해야 합니다
* 큰따옴표가 포함된 값은 두 번째 큰따옴표로 이스케이프해야 합니다
**파일 구조:**
OneSignal은 각 **폴더 경로를 고유한 데이터 소스로** 취급하며 파일 이름을 해당 경로 내 데이터의 버전으로 간주합니다. 이벤트를 처리할 때 OneSignal은 타임스탬프를 기반으로 선택한 폴더 경로에서 항상 최신 데이터를 선택합니다.
S3에서 이벤트 데이터를 업데이트할 때 기존 파일을 교체하거나 최신 버전을 추가할 수 있습니다. OneSignal은 새 이벤트를 처리하고 Custom Events API로 보냅니다.
### OneSignal용 IAM 역할 생성
OneSignal은 AWS 보안 모범 사례에 따라 역할 기반 인증을 사용하여 S3 버킷에 연결합니다.
OneSignal의 AWS 계정 ID (`341876425553`)에 대해 S3 버킷에 대한 읽기 전용 액세스를 제공하는 AWS 계정에서 IAM 역할을 생성합니다:
```bash theme={null}
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"
}]
}'
```
OneSignal 구성에 필요하므로 반환된 Role ARN을 저장하세요.
새로 생성된 역할에 S3 버킷에 대한 읽기 전용 액세스 권한을 부여합니다:
```bash theme={null}
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 연결 구성
OneSignal에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.
사용 가능한 통합 목록에서 **Amazon S3**를 선택합니다.
다음 정보를 제공합니다:
* **Region:** S3 버킷 리전
* **Bucket Name:** S3 버킷 이름
* **Role ARN:** 1단계의 IAM 역할 ARN
* **Prefix:** 이벤트 CSV 파일이 포함된 폴더 경로 (선택 사항)
OneSignal은 고유한 외부 ID를 생성하고 다음 화면에 표시합니다. IAM 역할을 업데이트하여 이 외부 ID를 요구하도록 합니다:
```bash theme={null}
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로 바꾸세요.
설정이 올바르게 작동하는지 확인하려면 OneSignal에서 **Test Connection**을 클릭하세요.
***
## CSV 처리 모드
OneSignal은 S3 버킷에서 이벤트 CSV 파일을 읽을 때 두 가지 모드를 지원합니다:
### Most Recent (기본값)
OneSignal은 구성된 S3 접두사 및 폴더 그룹에서 가장 최근 파일만 처리합니다. 단일 파일은 처리할 전체 이벤트 세트로 해석됩니다. 이 모드는 다음과 같은 경우에 잘 작동합니다:
* 단일 파일에 기간에 대한 모든 이벤트가 포함됨
* 업데이트된 이벤트 데이터로 시간이 지남에 따라 새 버전의 파일이 추가됨
* 전체 이벤트 배치를 한 번에 처리하고자 함
### Merge All
OneSignal은 구성된 S3 접두사 및 폴더 그룹의 모든 파일을 가져와 이벤트를 처리하기 전에 단일 데이터 세트로 병합합니다. 이 모드는 다음과 같은 경우에 유용합니다:
* 이벤트 데이터가 여러 파일로 분할됨
* 여러 소스의 이벤트를 처리하고자 함
* 새 이벤트로 점진적으로 파일이 추가됨
Merge All 모드에서는 모든 CSV 파일의 열 이름과 순서가 정확히 동일해야 합니다.
***
## 이벤트 데이터 매핑
연결되면 CSV 열을 OneSignal 사용자 지정 이벤트 필드에 매핑해야 합니다:
OneSignal은 이벤트 CSV 파일에서 열을 자동으로 감지하고 매핑을 제안합니다.
사용자 지정 이벤트에 필요한 필드를 매핑합니다:
* **Event Name** (필수): 이벤트의 이름/유형
* **External ID** (필수): External User ID
* **Event Timestamp** (선택 사항): 이벤트가 발생한 시간. 그렇지 않으면 현재로 간주됩니다.
이벤트 처리 빈도 및 전달 기본 설정을 설정합니다.
***
### 이벤트 데이터 매핑
{PLATFORM_0} {DATA_TYPE_0}를 OneSignal의 사용자 지정 이벤트 형식에 매핑합니다:
| OneSignal 필드 | {COLUMN_HEADER_0} | 설명 | 필수 |
| ------------- | ----------------- | -------------------------- | --- |
| `name` | `event_name` | 이벤트 식별자 | Yes |
| `external_id` | `user_id` | 사용자 식별자 | Yes |
| `timestamp` | `event_timestamp` | 이벤트가 발생한 시간 | No |
| `properties` | `event_data` | {PROPERTIES_DESCRIPTION_0} | No |
***
## 제한 사항
* **SQL 쿼리:** S3 소스는 이벤트 데이터에 대한 SQL 쿼리 또는 고급 변환을 지원하지 않습니다
* **파일 크기:** 개별 CSV 파일은 1GB를 초과하지 않아야 합니다
* **업데이트 빈도:** 최소 동기화 간격은 15분입니다
* **파일 유형:** CSV 파일만 지원됩니다 (JSON, Parquet 등은 지원되지 않음)
***
## FAQ
### CSV 파일에 형식 오류가 있으면 어떻게 되나요?
OneSignal은 잘못된 형식의 행을 건너뛰고 통합 대시보드에 자세한 오류 로그를 제공합니다. 일반적인 문제에는 필수 열 누락, 잘못된 타임스탬프 형식 및 일관되지 않은 열 수가 포함됩니다.
### OneSignal은 얼마나 자주 새 파일을 확인하나요?
OneSignal은 구성된 동기화 빈도에 따라 S3 버킷을 확인하며 최소 간격은 15분입니다.
***
## 도움이 필요하신가요?
S3 통합 설정에 대한 지원이 필요하면 `support@onesignal.com`으로 지원 팀에 문의하거나 인앱 채팅을 사용하세요.