Receiving Audience Segment Data

Overview

There are two preferred methods for receiving Audience segment data. The first method is running a self-hosted version of our On-Prem software. This software responds directly to bid-requests and automatically hosts and downloads audience data in an optimized format. To learn more about On-Prem, please consult our On-Prem documentation.

The second method is batch file delivery. With this method, raw mobile IFAs (IDFAs/AAIDs) for each audience segment is delivered by Foursquare to a partner’s AWS S3 bucket or SFTP server.


Batch File Delivery

Destination setup

To get started with batch file delivery, you’ll first need to set up a destination where Foursquare can deliver files. S3 buckets require specific permissions and SFTP destinations require that the appropriate credentials are provisioned and provided to Foursquare.

Amazon Web Services (AWS) S3

For Foursquare to deliver audience data to a partner’s S3 bucket, the destination bucket policy will need to contain the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowFactualFileOperations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::315898705177:role/FactualAudienceDataDelivery"
      },
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::$BUCKET/*"
    },
    {
      "Sid": "AllowFactualListOperations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::315898705177:role/FactualAudienceDataDelivery"
      },
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketNotification",
        "s3:PutBucketNotification"
      ],
      "Resource": "arn:aws:s3:::$BUCKET"
    }
  ]
}

SFTP

For Foursquare to deliver audience data to a partner’s SFTP server, you’ll need to provide either a username and password, or a username and identity file.

Username and Password

  1. Create an SFTP account
  2. Validate account has write access to the directory where data will be delivered
  3. Provide Foursquare the username and password via a secure route
  4. Provide SFTP server/port

Username and Identity File

  1. Create an SFTP account
  2. Generate an SSH Key Pair. This route may optionally have a password attached to the Identity File. The public key generated will be referred to as Identity File.
  3. Validate the username, identity file, and password combination has write access to the directory where data will be delivered.
  4. Provide Foursquare the username, identity file, and password combination via a secure route.
  5. Provide SFTP server/port.

File Format

Audience segments will be delivered as a single file to the configured destination. Each file will be gzipped and contain raw mobile IFAs, consisting of either IDFAs or AAIDs. Filenames will be formatted as follows: [design_id].tsv.gz. Design ID is the unique identifier for each audience segment. This ID, along with all other audience segment metadata can be accessed via our Management API.