Some ad network partners do not offer a reporting dashboard or API that allows Singular to directly access campaign and cost data. In these cases, partners may share data by granting Singular access to an Amazon s3 bucket.

If your partner uses this method, Singular can still process your campaign cost data--just follow the steps outlined below to set up and enable data ingestion from the s3 bucket.

Setting Up Sources with S3 Bucket Data Delivery

Once your partner is ready to deliver reports via s3, you will need to setup a Data Connector in Singular to enable data processing.

1. Go to Settings > Data Connectors in your Singular account.
2. Click Add a New Data Connector and enter the partner's name.
3. In the New Connector window, fill in the Folder Name--this should match the folder your partner created within the s3 bucket to deliver your reports.
4. Click Save.
5. Ask your partner to start delivering these daily reports to the S3 folder they created for your company.
6. 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.

For more information about adding data connectors, see the Data Connectors FAQ.

S3 Report Format & Bucket Permissions

You can use one of Singular's sample report templates as a starting point to share with your partner. These templatized formats are designed to include all the fields that Singular needs to process your campaign data.

• Fields highlighted in green are required and must be completed by your partner.
• Fields highlighted in blue are optional and should be included if applicable.

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.

[PartnerName]_[YourOrganizationName]_[YYYY-MM-DD].csv

Accepted file types are: .csv, .xls, .xlsx, .zip, .gzip (We cannot accept .txt files or a .txt from within a .zip file.)

S3 Bucket Permissions

1. The bucket name must start with "singular-sharing-data-"
   1. It is preferable to have the bucket hosted in us-west-1 or us-west-2
2. Your partner will provide Singular with access to their s3 bucket in one of the following ways:
   1. By sharing access key and secret credentials, or
   2. By granting access via IAM permissions. 

In many cases, the partner's s3 bucket will contain separate folders for each mutual client, including one of your organization.

If your partner is using IAM permissions, they'll need ton configure the appropriate bucket policy to grant Singular access. 

Below is an example of bucket policy. Where <YOUR_S3_BUCKET_NAME> appears, the partner should replace it with the actual name of their s3 bucket:

{
   "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 or if you need a different type of integration, such as a Mail or Google Doc integration.