FB Offline Conversions File Uploader

FB Offline Conversions File Uploader (referred as 'OCAFU' hereinafter) is a command line tool and node.js module that helps Facebook advertisers and marketing partners upload offline transactions to the FB marketing API without building their own application for API integration.

Why use OCAFU?

• Building API integration will require engineering resources and takes many development hours. Typically one engineer will need to spend about 3 weeks for development and testing to build reliable integration.
• In order to achieve the best possible match between your customers and FB users, the data needs to be normalized and hashed correctly. This tool uses the library written by FB to ensure the best possible match rate.
• For any issues with this tool, you will get support from Facebook.
• This tool will be updated periodically to support more advanced features.

Requirements

FB Offline Conversions File Uploader requires or works with

• Mac OS X, Linux, or Windows
• Offline conversions data in CSV format. Download Example Here
• User configured settings file. See example here
• User configured column mapping file. See example here
• FB App used for API calls. See this guide for instructions.
• FB system user token that has access to the offline event set used for the upload. For creating system user and token, see instructions here. (Regular user access token can be used, but using system user token is highly recommended)

Installing FB Offline Conversions File Uploader

OCAFU can be used in 3 different ways based on your environment and need:

(Note: If your organization does not support node.js, please see answer to question #2 in FAQ section below.)

Option 1: Install globally and use as command line tool

$ npm install -g offline-conversions-file-uploader
$ offline-conversions-file-uploader --accessToken YOUR_ACCESS_TOKEN... --uploadTagPrefix "Offline Sales xx/xx/xxxx"...

2017-05-15T15:52:52.265Z INFO Posting events 1 - 500 to http://graph.facebook.com/v2.9/00000000000000/events
2017-05-15T15:52:55.176Z INFO Rows 1 - 500 - Successfully uploaded 10 events.
...

Option2: Install locally and require the module to use it inside your own node app

$ npm install offline-conversions-file-uploader --save

(In your app's .js file)
const ocafu = require('offline-conversions-file-uploader');
ocafu.uploadConversionsFeed();

$ node your_app.js --accessToken YOUR_ACCESS_TOKEN... --uploadTagPrefix "Offline Sales xx/xx/xxxx"...

2017-05-15T15:52:52.265Z INFO Posting events 1 - 500 to http://graph.facebook.com/v2.9/00000000000000/events
2017-05-15T15:52:55.176Z INFO Rows 1 - 500 - Successfully uploaded 10 events.
...

Options 3. Build binary deployable to windows/linux/mac

$ git clone https://github.com/facebookincubator/offline-conversions-file-uploader

$ npm install
$ npm run build-binary (or build-binary-exe for Windows)
$./build/offline-conversions-file-uploader --accessToken YOUR_ACCESS_TOKEN... --uploadTagPrefix "Offline Sales xx/xx/xxxx"...

2017-05-15T15:52:52.265Z INFO Posting events 1 - 500 to http://graph.facebook.com/v2.9/00000000000000/events
2017-05-15T15:52:55.176Z INFO Rows 1 - 500 - Successfully uploaded 10 events.
...

How OCAFU works

This is a node.js application that will go through following steps to upload your offline conversions to FB's marketing API.

1. Read configurations and column mappings
2. Read input file in stream
3. For each line read, columns are normalized and hashed for upload.
4. Collect normalized and hashed data into batches (per batch size configured. Default: 500)
5. POST each batch to the API endpoint

How to use OCAFU

1. Install per instruction above.
2. Set up tool configuration file and column mapping file
3. Get access token for API calls
4. Run on command line or schedule execution with tools such as crontab

Available Configuration options

Configuration options can either be stored in a file (.yml format) or passed in as command line arguments. See following for available options:

|Option |Description | default | |-------------|-------------------|---------| |accessToken* | Access token for API call | | |apiVer| Version of FB marketing API used | v2.9 | |columnMappingFilePath| File containing column mapping info. For more info see Column Mapping File section below.|oca_column_mapping.json in current directory| |configFilePath*| File containing offline conversions data| oca_file_uploader.conf.yml in current directory. For more info about config options see Available Configuration options section below.| |dataSetId| ID of your offline event data set| | |inputFilePath| File containing offline conversions data | | |logging| Control the logging level of program (available options: silly, debug, info, warn, error)| info | |uploadTag| Tag to identify the events uploaded. Should use unique string for each distinct file uploaded. | Offline Conversions | |uploadTagPrefix| Instead of providing uploadTag, you can also define prefix (ex: Offline Conversions), then the tool will append filename/timestamp and use it as the uploadTag. If uploadTag is set, uploadTagPrefix is ignored. ex) Offline Conversions (example_events_big_100k.csv@1493837377000) | |

• These options can only be passed in as command line arguments and cannot be set in configuration file.

See example file here: here

Column Mapping File

You need to define what each column in the file is for. See an example here

and description of each key in the JSON file below:

| Field | Description | Required? | |-------|-------------|-----------| |header | Whether the file has header row or not | Yes | |delimiter | The delimiter for column. comma for CSV, tab for TSV, etc...| Yes | |mapping| The mapping for columns in the file. key-value pair represents "column index": "column type". For more detailed description for each column type, please see Column Types section below| Yes | |infoForNormalization| Format of your dob field to help with the normalization. See infoForNormalization section below for more info | No | |customTypeInfo| Info for the key-value pairs of custom_data fields. See customTypeInfo section below for more info. | No |

Column Types

|Column Type| Required? | Description | |-----------|-----------|-------------| |event_time | Yes | Use ISO8601 format or unixtime timestamp | |event_name | Yes | See event_time row in the data parameters table| |currency | Yes | Three-letter ISO currency for this conversion event. Required for Purchase events. | | value | Yes | Value of conversion event. Required for Purchase event. ex) 16.00 | | match_keys.xxxxx | Yes | The identifier info used to match people. xxxxx needs to be replaced with the match key type such as email, phone, etc... For list of available match key types, please see 'Key name' column in this table| | custom_data.xxxxx | No | Additional information about the conversion event. For example, send store location ID as custom_data.location_id or product category as custom_data.category |

infoForNormalization

For dob choose one of following format:

• MM/DD/YYYY
• DD/MM/YYYY
• YYYY/MM/DD
• MM/DD/YY
• DD/MM/YY
• YY/MM/DD

Note: '/' can be skipped (MMDDYYYY) or replaced with '-' (MM-DD-YYYY)

customTypeInfo

For each custom data column, add following JSON object to customTypeInfo.

If you added custom_data.store_num as one of the mapped columns in "mapping", you should add following:

"customTypeInfo": {
  "store_num" : {
    "key": "store_id",    // key used in upload
    "baseType": "number"  // number or string
  }
...
}

FAQ

1. My company has firewall which will block API calls to Facebook. What are my options?

• Whitelist FB IP's: Contact your security team to whitelist IP addresses returned by this command:

whois -h whois.radb.net -- '-i origin AS32934' | grep ^route

For more information, please refer to this guide which explains whitelisting for FB crawlers, but the same set of IP's are used for API servers.

• Request your security team to create DMZ where outbound HTTP request is allowed.

2. My company does not support running node.js. Can we still use file uploader?

• Pre-built binary executable files are available. Please contact FB team for access to these files. If your company has node.js install on any one of the machines, you could also try building these binary files using Option 3 above in the Installing FB Offline Conversions File Uploader section.l

Code organization

• /lib: Source code Transpiled to ES5 for npm
• /src: Original source code written in ES6 with FB's flow type system
• /cli.js: For when using OCAFU as command line tool
• /index.js: For when requiring OCAFU as a module
• /nexe.js: For building binary file with nexe

License

FB Offline Conversions File Uploader is BSD-licensed. We also provide an additional patent grant.