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.

Overview

We make Scheduled Log Exports API data available to you in one of three ways:

The data is delivered to your own cloud data service.
The data is stored in Branch's AWS S3 bucket.
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.
- Unified Analytics Export.
Data integrations for exports.
Webhook functionality.

Learn more on our pricing page.

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 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

Log in to AWS and navigate to the IAM dashboard, then go to Roles.
Select Create role.
Select S3 → S3 (in the "Select your use case" section).

5. Create your S3 bucket policy

Select Next: Permissions.
Select Create policy (in the "Attach permissions policy" section). This opens a new browser tab.
Choose the JSON tab.

Paste the following JSON, replacing instances of <bucket_name> with your S3 bucket name and <prefix> 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:::<bucket_name>"
               ]
           },
           {
               "Sid": "BranchExportsPut",
               "Effect": "Allow",
               "Action": [
                   "s3:AbortMultipartUpload",
                   "s3:DeleteObject",
                   "s3:GetObject",
                   "s3:ListBucket",
                   "s3:ListBucketMultipartUploads",
                   "s3:ListMultipartUploadParts",
                   "s3:PutObject"
               ],
               "Resource": [
                   "arn:aws:s3:::<bucket_name>/<prefix>/*"
               ]
           }
       ]
   }

Select Next: Tags, and add any tags.
Select Next: Review, and review your choices for this policy.
Enter a descriptive name for the policy. We recommend specifying "branch" in the policy name.
Select Create policy.

6. Configure your S3 bucket policy

Navigate back to your original browser tab. Select the refresh button above the table of policies.
Search by name for the policy you just created.
Select the checkbox next to the policy, then select Next: Tags and add any tags.
Select Next: Review and review the choices you made for this role.
Enter a name for this role. The role name must start with the substring Branch-Export-Upload for Branch to recognize it.
Select Create role to complete role creation.

7. Configure your S3 bucket role's trusted entities

Select your newly created role to edit it.
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-\*.
Select the Trust relationships tab.
Select Edit trust relationship.

Paste the following JSON, replacing <external_id> 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": "<external_id>"
        }
      }
    }
  ]
}

8. Export data from Branch to AWS

Once you've completed all the steps above, you can create a new Scheduled Log Exports subscription to start exporting data.

Make sure to set destination.subscription_type to cloud and set destination.cloud to s3 in the request body. 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 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 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:

Navigate to the IAM & Admin dashboard, then go to Roles.
Use the drop-down to make sure you're creating the role within the correct project.
Select Create Role, and give the role a name, such as Branch SLE Object List.
Select Add Permissions, and give the role the storage.objects.list permission.

To create the second role:

Select Create Role, and give the role a name, such as Branch SLE Upload.
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

Within the IAM & Admin dashboard, go to Service Accounts.
Select Create Service Account.
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

Go to the Permissions tab for the new service account.
In the "View By Principals" section, select the Grant Access button.
Add a new principal that points to Branch's service account: gcs-sle-prod-usw1**@**project-sle-prod.iam.gserviceaccount.com
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.

Navigate to Cloud Storage, then Buckets.
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

Go to the bucket details, then to the Permissions tab.
In the "View By Principals" section, select the Grant Access button.
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.
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.
For the Branch SLE Upload role, add an IAM condition. Give the condition a descriptive title, such as Permit SLE Upload to Bucket.
In the Condition Editor tab for the IAM condition, add a resource.name.startsWith statement, which contains the following values:
1. <YOUR-BUCKET> is the name you gave to the new bucket you created.
2. <YOUR-PREFIX> is the folder path within the bucket where you want to put Branch data.
3. <YOUR-EXTERNAL-ID> is the external ID you retrieved from the Scheduled Log Exports API.
Generic format
javascript
```
resource.name.startsWith("projects/_/buckets/<YOUR-BUCKET>/objects/<YOUR-PREFIX>/external_id=<YOUR-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 to start exporting data.

Make sure to set destination.subscription_type to cloud and set destination.cloud to gcs in the request body. 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

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.

Scheduled Log Exports Cloud Setup

Overview ​

Access ​

Cloud configuration ​

Amazon Web Services ​

Google Cloud Platform ​

Overview

Access

Cloud configuration

Amazon Web Services

Google Cloud Platform