SFTP Integration Guide

Rokt Ads SFTP integration enables advertisers to securely send conversion and audience data to Rokt in batch using customer identifiers and attributes. This integration allows Rokt to close the loop between ad exposure and downstream outcomes, enabling better optimization and performance for our advertisers.

Prerequisites

Before you begin, ensure you have:

• Access to an SFTP client (e.g., FileZilla, WinSCP, or command-line sftp)
• A Keybase account for secure credential exchange
• Your Rokt Account Manager's contact information

1. Create CSV files

Prepare CSV files following these guidelines.

File format requirements

• Files must adhere to RFC 4180 CSV format standards.
• Supported file formats:
  • Plain CSV (.csv)
  • ZIP archive containing one or more CSV files (.zip)
  • Gzip-compressed CSV (.csv.gz)
  • PGP-encrypted files with .gpg extension (e.g., .csv.gpg or .csv.gz.gpg). Contact your Rokt Account Manager for Rokt's public key.
• File size: 5 MB – 2 GB (optimal). Split larger datasets into multiple files for parallel processing.
• Maximum 50 columns per file.
• Maximum row size: 80 KB.
• All column names must be unique.
• Do not use subfolders when uploading.

File naming

Use the following naming convention based on your data type:

Data Type	File Name Pattern	Example
Audience data	<name>-eventless.csv	premium_users-eventless.csv
Event/conversion data	<name>-custom_event.csv	purchases-custom_event.csv

attention

Avoid dashes (-) and dots (.) in the <name> portion of your file name. The dash before eventless or custom_event is required.

Data requirements

Each row must include at least one valid user.

remarque

Rows missing valid identity values will fail processing. Ensure at least one identity column contains a value for every row.

Root-level fields

Column Name	Example Value	Notes
environment	development	Environment identifier (e.g., development, production).
ip	8.8.8.8	User's IP address.

Event attributes

For conversion/event data, include the following columns:

Column Name	Example Value	Required	Notes
events.data.timestamp_unixtime_ms	1699123456789	Yes	Event timestamp in Unix milliseconds.
events.data.event_name	conversion	Yes	Always set to conversion.
events.data.custom_event_type	transaction	Yes	Always set to transaction.
events.data.custom_attributes.conversiontype	purchase	Yes	The type of action the user performed (e.g., signup, purchase, install).
events.data.custom_attributes.confirmationref	ORD-54321	Yes	Unique reference for deduplication.
events.data.custom_attributes.amount	99.99	No	Transaction amount (numeric). Include where applicable.

User identities

Column Name	Example Value	Notes
user_identities.email	j.smith@example.com	User's email address (plaintext).
user_identities.other	fab1e2e699b3b927cbf875046a64f222	Hashed email or other identifier. Use SHA-256. Lowercase and trim trailing spaces before hashing.

User attributes

Include as many of the following attributes as available to improve matching:

Column Name	Example Value	Notes
user_attributes.FirstName	John	Customer's first name.
user_attributes.FirstNameSha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash of first name. Lowercase and trim spaces before hashing.
user_attributes.LastName	Doe	Customer's last name.
user_attributes.LastNameSha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash of last name. Lowercase and trim spaces before hashing.
user_attributes.Mobile	3125551515	Phone number. Accepts 1112345678 or +1 (222) 345-6789 formats.
user_attributes.MobileSha256	fab1e2e699b3b927cbf875046a64f222	SHA-256 hash. Format as 5551234567 (digits only, no country code).
user_attributes.Age	33	Customer's age.
user_attributes.Dob	19900717	Date of birth in YYYYMMDD format.
user_attributes.Gender	M	Customer's gender: M, Male, F, or Female.
user_attributes.City	Brooklyn	Customer's city.
user_attributes.State	NY	Customer's state (two-letter code for US).
user_attributes.Zip	11201	Customer's zip/postal code.
user_attributes.Title	Mr	Customer's title: Mr, Mrs, Ms, etc.
user_attributes.Language	en	ISO 639-1 language code.
user_attributes.Value	52.25	Customer's monetary value.
user_attributes.PredictedLtv	136.23	Predicted lifetime value of the customer.

Device identities

Column Name	Example Value	Notes
device_info.http_header_user_agent	Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X)	Browser or device user agent string.
device_info.android_advertising_id	38400000-8cf0-11bd-b23e-10b96e40000d	Google Advertising ID (GAID) for Android.
device_info.android_uuid	550e8400-e29b-41d4-a716-446655440000	Android device UUID.
device_info.ios_advertising_id	38400000-8cf0-11bd-b23e-10b96e40000d	iOS Advertising ID (IDFA).
device_info.ios_idfv	550e8400-e29b-41d4-a716-446655440000	iOS Identifier for Vendor (IDFV).

Audience attributes

For audience data, use one column per audience segment. Prefix the attribute name with audience_ (e.g., user_attributes.audience_premium_users).

Column Name	Example Value	Notes
user_attributes.audience_all_users	True	True to add user to audience; False to remove.
user_attributes.audience_premium_users	True	True if premium member; False to remove from segment.
user_attributes.audience_retargeting	False	True to add to retargeting list; False to remove.

Example CSV files

Download sample files to use as templates:

Data Type	Sample File
Audience data	RoktSample_audience-eventless.csv
Event/conversion data	RoktSample-custom_event.csv

2. Get SFTP credentials

Rokt uses Keybase for secure credential exchange.

SFTP server details:

• Host: sftp.mparticle.com
• Port: 4422

To obtain your credentials:

1. Create a Keybase account at keybase.io using your work email.
2. Share your Keybase username with your Rokt Account Manager.
3. Your Account Manager will send your SFTP credentials via encrypted Keybase chat.

astuce

Keep your credentials secure. Do not share them via email or other unencrypted channels.

3. Upload CSV files

1. Connect to the SFTP server:

sftp -P 4422 your_username@sftp.mparticle.com

2. Navigate to or create the drop folder structure:

cd drop
mkdir US2-123456789123456789  # Use the folder name provided by your Account Manager
cd US2-123456789123456789

3. Upload your CSV files:

put premium_users-eventless.csv

attention

Verify there are no trailing spaces in folder names. The folder name is case-sensitive.

What happens next

Files are added to the processing queue immediately after upload. Contact your Rokt Account Manager if you need to verify successful processing or encounter any issues.