> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt). # Scheduled Log Exports Cloud Setup This guide walks you through configuration setup for the cloud account you want to send your Branch Scheduled Log Exports API data to. For general information about the Scheduled Log Exports API, visit the API Reference [guide](https://help.branch.io/apidocs/scheduled-log-exports/overview.md). ## Overview We make Scheduled Log Exports API data available to you in one of three ways: 1. The data is delivered to your own cloud data service. 2. The data is stored in Branch's AWS S3 bucket. 3. The data is delivered to you via email. This guide walks you through the cloud configuration steps for option 1 (sending the data to your own cloud service provider). Branch supports exporting to either **Amazon Web Services (AWS)** or **Google Cloud Platform (GCP)**. ### Access Access to the Scheduled Log Exports API requires our **Advanced Data Feeds** add-on. The Advanced Data Feeds add-on also includes access to: - The Cross-Events Export [API](https://help.branch.io/apidocs/cross-events-export/overview.md). - [Unified Analytics Export](https://help.branch.io/apidocs/cross-events-export/unified-analytics-export.md). - Data integrations for [exports](https://help.branch.io/marketer-hub/supported-data-integration-partners.md). - Webhook [functionality](https://help.branch.io/marketer-hub/webhooks.md). Learn more on our pricing [page](https://www.branch.io/pricing/). ## Cloud configuration ### Amazon Web Services **1. Get external ID from Branch** We provide a unique external ID for your Branch account. You'll need this ID when you configure your S3 bucket role's trusted entities in step 7. The Scheduled Log Exports API has an [endpoint](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#get-external-id) that you can use to retrieve your external ID. **2. Create S3 bucket** To start, create a new bucket in S3 that will store your Branch Scheduled Log Exports API data. Make sure that it's logically separate from your existing S3 buckets. Note the name of this bucket. **3. Create folder within S3 bucket** Create a folder within your new S3 bucket. This folder name is considered the prefix in the destination path you pass to the API. **4. Create your S3 bucket role** 1. Log in to AWS and navigate to the IAM dashboard, then go to [Roles](https://console.aws.amazon.com/iamv2/home#/roles). 2. Select **Create role**. 3. Select **S3 → S3** (in the "Select your use case" section). **5. Create your S3 bucket policy** 1. Select **Next: Permissions**. 2. Select **Create policy** (in the "Attach permissions policy" section). This opens a new browser tab. 3. Choose the **JSON** tab. 4. Paste the following JSON, replacing instances of `` with your S3 bucket name and `` with the name of the folder you created: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListObjectsInBucket", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::" ] }, { "Sid": "BranchExportsPut", "Effect": "Allow", "Action": [ "s3:AbortMultipartUpload", "s3:DeleteObject", "s3:GetObject", "s3:ListBucket", "s3:ListBucketMultipartUploads", "s3:ListMultipartUploadParts", "s3:PutObject" ], "Resource": [ "arn:aws:s3::://*" ] } ] } ``` 5. Select **Next: Tags**, and add any tags. 6. Select **Next: Review**, and review your choices for this policy. 7. Enter a descriptive name for the policy. We recommend specifying "branch" in the policy name. 8. Select **Create policy**. **6. Configure your S3 bucket policy** 1. Navigate back to your original browser tab. Select the refresh button above the table of policies. 2. Search by name for the policy you just created. 3. Select the checkbox next to the policy, then select **Next: Tags** and add any tags. 4. Select **Next: Review** and review the choices you made for this role. 5. Enter a name for this role. **The role name must start with the substring** `Branch-Export-Upload` **for Branch to recognize it**. 6. Select **Create role** to complete role creation. **7. Configure your S3 bucket role's trusted entities** 1. Select your newly created role to edit it. 2. You'll see a summary, including a Role ARN. Note this value, as you'll use it when you set up a new Scheduled Log Exports API subscription. The format of a Role ARN looks like `arn:aws:iam::xxxxxxxxxxxx:role/Branch-Export-Upload-\*`. 3. Select the **Trust relationships** tab. 4. Select **Edit trust relationship**. 5. Paste the following JSON, replacing `` with the Branch external ID you retrieved from the Scheduled Log Exports API earlier: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::772300342379:role/BranchTMRoleProdDataPlatformExports" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ] } ``` **8. Export data from Branch to AWS** Once you've completed all the steps above, you can [create a new Scheduled Log Exports subscription](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#create-new-subscription) to start exporting data. Make sure to set `destination.subscription_type` to `cloud` and set `destination.cloud` to `s3` in the [request body](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#create-new-subscription). You must also set the following parameters: - `destination.resource_access_id` (the ARN for the AWS role) - `destination.bucket` (name of S3 bucket) - `destination.prefix` (for `s3://my-branch-export-bucket/my-folder/`, the prefix would be `my-folder`) **9. Check S3 for data** Once you've created a subscription and a job associated with it has successfully run, the `report.subscription_status` field is in the `ACTIVE` state. You can [check the state](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#get-details-on-single-subscription) with the Scheduled Log Exports API. At this point, you can visit your S3 bucket to look for Branch data. We place exports into subfolders, as shown in this example: `s3://my-branch-export-bucket/my-folder/subscription_id=1d7d7c2e-175b-11ec-9621-0242ac130002/report_type=eo_install/y=2021/m=09/d=17/h=00/` Remember to decompress the files before attempting to read the data. ### Google Cloud Platform **1. Get external ID from Branch** We provide a unique external ID for your Branch account. The Scheduled Log Exports API has an [endpoint](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#get-external-id) that you can use to retrieve your external ID. **2. Create custom roles for bucket access** Preexisting bucket roles in GCP offer more permissions than are required by the Scheduled Log Exports API, so we recommend that you create two custom roles with more limited permissions. To create the first role: 1. Navigate to the IAM & Admin dashboard, then go to [Roles](https://console.cloud.google.com/iam-admin/roles). 2. Use the drop-down to make sure you're creating the role within the correct project. 3. Select **Create Role**, and give the role a name, such as `Branch SLE Object List`. 4. Select **Add Permissions**, and give the role the `storage.objects.list` permission. To create the second role: 1. Select **Create Role**, and give the role a name, such as `Branch SLE Upload`. 2. Select **Add Permissions**, and give the role three permissions: 1. `storage.objects.create` (allows for creating objects in a bucket) 2. `storage.objects.get` (primarily used for folder cleanup in the event of upload failures) 3. `storage.objects.delete` (primarily used for folder cleanup in the event of upload failures) **3. Create new service account** 1. Within the IAM & Admin dashboard, go to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts). 2. Select **Create Service Account**. 3. Give the new service account a name and ID, for example, `branch-sle-service-acct`. You can give the service account any name you want, and you can use the same value for the name as you do for the ID. **4. Configure service account** 1. Go to the **Permissions** tab for the new service account. 2. In the "View By Principals" section, select the **Grant Access** button. 3. Add a new principal that points to Branch's service account: **gcs-sle-prod-usw1****@****project-sle-prod.iam.gserviceaccount.com** 4. Give the new principal the preexisting GCP role called `Service Account Token Creator`. **5. Create new bucket** Create a new bucket that will store your Branch Scheduled Log Exports API data. Make sure it's logically separate from your other buckets. 1. Navigate to **Cloud Storage**, then **Buckets**. 2. Select the **Create** button, and give the bucket a name. **6. Create folder within bucket** Create a folder within your new bucket. This folder name is considered the prefix in the destination path you pass to the API. **7. Configure bucket** 1. Go to the bucket details, then to the **Permissions** tab. 2. In the "View By Principals" section, select the **Grant Access** button. 3. In the **New principals** box, add the ID for the new service account you created, which we called `branch-sle-service-acct` in this example. 4. Under the "Assign roles" section, assign access to the two roles you created earlier, which we called `Branch SLE Object List` and `Branch SLE Upload` in this example. 5. For the `Branch SLE Upload` role, add an IAM condition. Give the condition a descriptive title, such as `Permit SLE Upload to Bucket`. 6. In the **Condition Editor** tab for the IAM condition, add a `resource.name.startsWith` statement, which contains the following values: 1. `` is the name you gave to the new bucket you created. 2. `` is the folder path within the bucket where you want to put Branch data. 3. `` is the external ID you [retrieved](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#get-external-id) from the Scheduled Log Exports API. **Generic format** ```javascript resource.name.startsWith("projects/_/buckets//objects//external_id=/") ``` **Example** ```javascript // `my-branch-bucket` is the bucket name // `branch/important_reports` is the prefix // `0a0a0-a0a0a0a-0a0a0a` is the external ID resource.name.startsWith("projects/_/buckets/my-branch-bucket/objects/branch/important_reports/external_id=0a0a0-a0a0a0a-0a0a0a/") ``` **8. Export data from Branch to GCP** Once you've completed all the steps above, you can [create a new Scheduled Log Exports subscription](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#create-new-subscription) to start exporting data. Make sure to set `destination.subscription_type` to `cloud` and set `destination.cloud` to `gcs` in the [request body](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#create-new-subscription). You must also set the following parameters: - `destination.resource_access_id` (the full service account name, which looks like an email address, for example, `branch-sle-service-acct@your-sle-project.iam.gserviceaccount.com`) - `destination.bucket` (name of GCP bucket; for `/buckets/my-branch-bucket/objects/branch/important_reports/`, this would be `my-branch-bucket`) - `destination.prefix` (the prefix path for the bucket; for `/buckets/my-branch-bucket/objects/branch/important_reports/`, this would be `branch/important_reports`) **9. Check GCP for data** Once you've created a subscription and a job associated with it has successfully run, the `report.subscription_status` field is in the `ACTIVE` state. You can [check the state](https://help.branch.io/apidocs/scheduled-log-exports/overview.md#get-details-on-single-subscription) with the Scheduled Log Exports API. At this point, you can visit your GCP bucket to look for Branch data. Make sure to look inside the prefix path you defined during configuration, which may include folders. Remember to decompress the files before attempting to read the data.