Setting Up an S3 Bucket Data Connector

For general instructions for setting up Singular to receive data, see the Data Connectors FAQ.

Some ad network partners do not have a reporting dashboard or API for Singular to query campaign and cost data from. Instead, the partner may provide the campaign data by permissioning Singular with a S3 bucket from which to retrieve your data.

Singular can process data from such sources if you follow these steps.

Setting Up Sources with S3 Bucket Data Delivery

  1. Add a data connector for the new partner.
    • Go to Settings > Data Connectors.
    • Click Add a New Connector and enter the partner's name.
    • In the New Connector window, enter the "Folder Name" that the partner has created within the S3 bucket to deliver your data.
    • Click Save.
    For more information about adding data connectors, see the Data Connectors FAQ.
  2. Contact us to let us know you have activated the new Data Connector and need the Folder Name activated on Singular's Data Connector. Singular Support will ensure this is done and notify you that the S3 bucket is now ready to process the reports your partner delivers to the folder.
  3. Ask your partner to start delivering these daily reports to the S3 folder they created for your company.

S3 Report Format & Bucket Permissions

You can share this email report template with your partner. The fields highlighted in green are required from your partner in order for Singular to process your campaign data. The fields in blue should be included if applicable, but are not necessary.

The file name should include the partner name (as it appears in singular), your organization's name, and the date of the new file delivered each day.

S3 Bucket Permissions

  1. The bucket name must start with "singular-sharing-data-"
    • It is preferable to have the bucket hosted in us-west-1 or us-west-2.
  2. Provide access to the s3 bucket either by providing us with access and secret keys or using IAM permissions. Please see below for what bucket policy needs to be configured if you grant us access via IAM permissions. (Where <YOUR_S3_BUCKET_NAME> appears in the example below, you should insert your s3 bucket name.)
{
"Version":"2012-10-17",
"Id":"",
"Statement":[
{
"Sid":"SingularS3Access",
"Effect":"Allow",
"Principal":{
"AWS":[
"arn:aws:iam::623184213151:role/singular-sharing-s3-role"
]
},
"Action":[
"s3:GetObject",
"s3:ListBucket",
"s3:GetBucketLocation"
],
"Resource":[
"arn:aws:s3:::<YOUR_S3_BUCKET_NAME>",
"arn:aws:s3:::<YOUR_S3_BUCKET_NAME>/*"
]
}
]
}

Best Practices

  • Your partner should deliver the reports daily, before 07:00 AM UTC if possible or by midnight in your reporting timezone with the previous days' data.
  • For mobile campaigns, the partner should separate the platforms by iPhone, iPad or Android.
  • Campaign names should be as descriptive as possible, including app names, platform*, country, etc., when applicable.
  • The reports should be cumulative per month - i.e., each report should contain all the days prior to it for a given month.
  • Have reports sent to both Singular and yourself so you can easily tell if Singular is receiving the reports.
  • Make sure that your partner provides the reports with a consistent format/header and file naming conventions (time/date stamps) to avoid any processing issues.

*For non-mobile campaigns, we do not expect to receive a "platform" breakdown of cost data, but having this information in the campaign name will allow advertisers to understand the platform on which their ad/creative was targeted and on which mobile platform (iOS or Android) the audience converted.

How to Contact Singular

Contact us to let us know if there are problems with data ingestion from a partner's Data Connector.
contact_form.gif