Setup Instructions

1. Obtain a Service Account

Option A: Create a New Service Account (Recommended)

1. In the Google Cloud platform, go to IAM & Admin > Service Accounts and click Create Service Account.

2. Enter a name, an ID, and a description for the service account and click Create.

   

3. To create a JSON key for the account, click Create Key. Under Key Type, choose "JSON", and click Create.

   

4. Download the key file and keep it - you will need to upload it to Singular in step 3 below.

Option B: Use Singular's Existing Service Account

You can use Singular's existing account: singular-etl@singular-etl.iam.gserviceaccount.com. You will grant this account the necessary permissions in step 3 below.

2. Create a New Bucket

To create a bucket:

1. In the Google Cloud Platform dashboard, go to the Storage section and click Create Bucket.

2. Pick a name for the bucket. We recommend picking a name that indicates that this bucket is for Singular's data destination (ETL).

   

3. Under Choose where to store your data, select your preferred location. If you don't have a specific preference, we recommend using the default options of "Multi-region" and "us".

   

4. Under Choose a default storage class for your data, select "Standard" (your data will be accessed several times a day).

   

5. Under Choose how to control access to objects, select "Fine-grained".

   

6. Under Advanced Settings, leave all the default options unchanged, and click Create.

3. Grant Permissions

After creating the bucket:

1. Switch to the Permissions tab and click Add members.

   

2. If you chose to use Singular’s existing GCS account, enter the following email address: singular-etl@singular-etl.iam.gserviceaccount.com. Otherwise, use your own account that you have created in section #2.

3. Under Add members and roles, select the role "Storage Object Admin". This allows Singular to write files, delete files, and check if any files exist in the bucket.

   

4. Add a GCS Data Destination

Finally, to add a GCS data destination in Singular:

1. In your Singular account, go to Settings > Data Destinations and click Add a new destination.
2. Type in either "GCS Destination" (to export aggregated marketing data) or "GCS User-Level Destination" (to export user-level data).

3. In the window that opens, fill in the relevant details:

   Field	Description
   Bucket Name	Enter the Bucket name from Step #2.
   Service Account Type	Choose the appropriate service account type (user-created or Singular's pre-made) based on Step #1.
   Credentials File	Upload the file you created in Step #1, wouldn't show if you chose to give access to Singular's pre-made Service Account.
   Output File Format	Select an output format: "CSV" or "Parquet".
   Data Schema	The schema of the data loaded into the destination. For your schema options, see Data Destinations: Aggregated Marketing Data Schemas and Data Destinations: User-Level Data Schemas.
   Output Key Pattern	The format of the file name to create. See the table below for optional placeholders you can use.

Singular supports several placeholders (macros) that will get expanded automatically: