Skip to content
This repository has been archived by the owner on Sep 1, 2022. It is now read-only.

Commit

Permalink
support customer_file_source for CA
Browse files Browse the repository at this point in the history 
Summary:
Several changes.

1. Add support for customer_file_source for CA upload.
https://developers.facebook.com/ads/blog/post/2018/06/13/sharing-custom-audiences/

2. Add upload_source support for Offline API. This is used by backend to distinguish between MDFU and API in a heuristic way.

3. Deprecate MDFU V1 in readme.

Reviewed By: kefei-cs19

Differential Revision: D8728385

fbshipit-source-id: aa62952
  • Loading branch information
@facebook-github-bot
Yuetao Xu authored and facebook-github-bot committed Jul 5, 2018
1 parent cf59ed1 commit c4576ae
Show file tree
Hide file tree
Showing 20 changed files with 694 additions and 23 deletions.
5 changes: 2 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Once you make sure an upload is made successfully, you can automate your upload
|validate|Do a dry-run and validate some sample rows.|**`accessToken`** **`configFilePath`** **`dataSetID`** **`inputFilePath`** **`mapping`** `customTypeInfo` `delimiter` `format` `header` `logging` `namespaceID` `numRowsToValidate` `presetValues` `reportOutputPath`|
|preprocess|Hash the CSV file and store it locally without sending it Facebook. It also normalizes other fields, such as converting ISO-formatted event time into unix time.|**`inputFilePath`** **`configFilePath`** **`mapping`** `customTypeInfo` `delimiter` `format` `header` `ignoreSampleErrors` `logging` `preprocessOutputPath` `presetValues` `reportOutputPath`|
|upload-preprocessed|Upload the hashed CSV generated by `preprocess` command.|**`accessToken`** **`dataSetID`** **`inputFilePath`** `batchSize` `configFilePath` `ignoreSampleErrors` `logging` `namespaceID` `reportOutputPath` `skipRowsAlreadyUploaded` `uploadID` `uploadTag` `uploadTagPrefix`|
|upload-audience|Add or remove users to/from your custom audience.|**`accessToken`** **`configFilePath`** **`inputFilePath`** **`mapping`** `adAccountID` `appIDs` `batchSize` `customAudienceID` `delimiter` `format` `header` `ignoreSampleErrors` `logging` `pageIDs` `removeUsers` `reportOutputPath`|
|upload-audience|Add or remove users to/from your custom audience.|**`accessToken`** **`configFilePath`** **`customFileSource`** **`inputFilePath`** **`mapping`** `adAccountID` `appIDs` `batchSize` `customAudienceID` `delimiter` `format` `header` `ignoreSampleErrors` `logging` `pageIDs` `removeUsers` `reportOutputPath`|

## Options
### How to Specify
Expand Down Expand Up @@ -108,6 +108,7 @@ Here is a list of all options we support. See previous section for options suppo
| reportOutputPath | Path of output report of each command. The report contains summary, issues and error samples. The file will be truncated if it already exists. | CLI or Config JSON | `"report.txt"` | `"upload-report.txt"` |
| adAccountID | ID of your ad account if you are creating a new audience with this upload. | CLI or Config JSON | *No default* | `"123456789"` |
| customAudienceID | ID of your custom audience if you are uploading to an existing audience. | CLI or Config JSON | *No default* | `"123456789"` |
| customFileSource | Describes how the customer information in your Custom Audience was originally collected. | CLI or Config JSON | `USER_PROVIDED_ONLY`, `PARTNER_PROVIDED_ONLY`, `BOTH_USER_AND_PARTNER_PROVIDED` | `"USER_PROVIDED_ONLY"` |
| removeUsers | Remove uploaded users from custom audience. | CLI or Config JSON | `false` | `true` |
| appIDs | A list of app IDs when appuid is mapped. | Config JSON Only | *No default* | `["123456789", "987654321"]` |
| pageIDs | A list of page IDs when pageuid is mapped. | Config JSON Only | *No default* | `["123456789", "987654321"]` |
Expand Down Expand Up @@ -229,8 +230,6 @@ Use this tool whenever possible, the MDFU will be deprecated soon. This tool pro
* It supports a validate command which does a dry-run on some sample rows of your data file, so you have a chance to fix the issue before sending them to Facebook.
* It supports resuming, so you can upload same file again without causing duplications.

In short, if you want to upload offline conversions, use this tool. If you want to upload custom audiences, use MDFU.

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

- Whitelist Facebook IP's: Contact your security team to whitelist IP addresses returned by this command:
Expand Down
28 changes: 20 additions & 8 deletions demo-audience/demo.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ If you don't have audience ID yet, you can use ad account ID.
```
export ad_account_id='YOUR_AD_ACCOUNT_ID_HERE'
```
Then when adding users, replace `--customAudienceID $audience_id` with `--adAccountID $ad_account_id`. The tool will auto create an ID for you. When deleting users from custom audiece, audience ID is always required.
Then when adding users, replace `--customAudienceID $audience_id` with `--adAccountID $ad_account_id`. The tool will auto create an ID for you. When deleting users from custom audience, audience ID is always required.

`customerFileSource` is always required when creating custom audience. See this [post](https://developers.facebook.com/ads/blog/post/2018/06/13/sharing-custom-audiences/) for available options.

# Run Demos

Expand All @@ -29,7 +31,8 @@ node lib/cli.js upload-audience \
--configFilePath demo-audience/config-test-email-10k.json \
--inputFilePath demo-audience/test-email-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY
```

Delete users
Expand All @@ -40,6 +43,7 @@ node lib/cli.js upload-audience \
--inputFilePath demo-audience/test-email-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY \
--removeUsers
```

Expand All @@ -52,7 +56,8 @@ node lib/cli.js upload-audience \
--configFilePath demo-audience/config-test-rich-10k.json \
--inputFilePath demo-audience/test-rich-clean-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY
```

Delete users
Expand All @@ -63,6 +68,7 @@ node lib/cli.js upload-audience \
--inputFilePath demo-audience/test-rich-clean-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY \
--removeUsers
```

Expand All @@ -75,7 +81,8 @@ node lib/cli.js upload-audience \
--configFilePath demo-audience/config-test-rich-10k.json \
--inputFilePath demo-audience/test-rich-dirty-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY
```

The above command will fail because it will abort upload after detecting that more than 10% of the sample rows contain error. Use `--ignoreSampleErrors` option to forcefully upload.
Expand All @@ -93,7 +100,8 @@ node lib/cli.js upload-audience \
--configFilePath demo-audience/config-test-email-value-10k.json \
--inputFilePath demo-audience/test-email-value-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY
```

Remove users
Expand All @@ -104,6 +112,7 @@ node lib/cli.js upload-audience \
--inputFilePath demo-audience/test-email-value-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY \
--removeUsers
```

Expand All @@ -115,6 +124,7 @@ node lib/cli.js upload-audience \
--inputFilePath demo-audience/test-email-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY \
--removeUsers
```

Expand All @@ -127,7 +137,8 @@ node lib/cli.js upload-audience \
--configFilePath demo-audience/config-test-rich-value-10k.json \
--inputFilePath demo-audience/test-rich-clean-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY
```

Remove users
Expand All @@ -138,6 +149,7 @@ node lib/cli.js upload-audience \
--inputFilePath demo-audience/test-rich-clean-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY \
--removeUsers
```

Expand All @@ -151,8 +163,8 @@ node lib/cli.js upload-audience \
--configFilePath demo-audience/config-test-rich-value-10k.json \
--inputFilePath demo-audience/test-rich-dirty-10k.csv \
--accessToken $access_token \
--customAudienceID $audience_id
--customAudienceID $audience_id \
--customerFileSource USER_PROVIDED_ONLY
```

The above command will fail because it will abort upload after detecting that more than 10% of the sample rows contain error. Use `--ignoreSampleErrors` option to forcefully upload.

Loading

0 comments on commit c4576ae

Please sign in to comment.