SFTP Events Integration Guide

The Rokt Ads SFTP integration enables advertisers and technology partners to securely send conversion and event data to Rokt in batches formatted as one or more .csv files. Sending your conversion data to Rokt closes the loop between ad exposure and downstream outcomes, enabling better campaign optimization and overall performance for advertisers in the Rokt network.

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:

File Name Pattern	Example
<name>-custom_event.csv	purchases-custom_event.csv

注意

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

Data requirements

Each row must include at least one valid user.

注記

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	production	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).

Example CSV files

Download a sample file to use as a template:

RoktSample-custom_event.csv

2. Get SFTP credentials

Rokt uses Keybase for secure credential exchange.

SFTP server details:

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

SFTP clients (e.g. FileZilla, WinSCP)

When using a graphical SFTP client, use Host sftp.us2.mparticle.com, Protocol SFTP, and Port 4422 (or paste sftp://sftp.us2.mparticle.com if your client accepts a full URL). Enter the username and password from your Account Manager when prompted.

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.

ヒント

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.us2.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 purchases-custom_event.csv

注意

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.