Marketing API

Data Processing Options for Users in California

We've released a Limited Data Use feature to give businesses more control over how their data is used in our systems and better support them with their California Consumer Privacy Act (CCPA) compliance efforts.

Businesses can send Facebook a parameter to indicate that a person in California is opted out of the sale of data or that the business has opted to have Facebook process data as a service provider, as defined by the CCPA. The signal is sent through an array called Data Processing Options, and it can optionally include a user’s country and state.

If a user is opted out of the sale of their data on the business’ website or the business opts to have Facebook process data as a service provider, the business can choose to send Facebook the parameter through an API call. This flag indicates that Facebook should limit its use of California personal information for a given event.

If we receive a flag for a person in California, we will process data in accordance with our role as a service provider and limit the use of that data subject to our State-Specific Terms. Limited Data Use is only effective for people in California. If businesses do not set the parameters to US and California, we will determine if a person is in California. Businesses may notice an impact to campaign performance and effectiveness, and retargeting and measurement capabilities will be limited.

Supported APIs are listed below, and other Facebook Products with Limited Data Use are described in our State-Specific Terms. If your business uses an API or other Facebook Product that isn’t supported in our initial release, with few exceptions, we will not act as your service provider for those APIs starting July 1, 2020.

To give businesses time to implement this feature, we will apply Limited Data Use to all personal information they share about people in California for the following Facebook Products during a transition period, detailed below.

Facebook ProductTransition Period

App Events via Facebook SDK (terms)

Jul 1, 2020 until Facebook gives 60 days' notice for ending the Transition Period or until you upgrade to Facebook SDK v7.1.1 or higher for iOS, v7.1.0 or higher for Android and v7.21.1 or higher for Unity, whichever is sooner.

Audience Network Ad Request and Bidding via Audience Network SDK (terms)

Jul 1, 2020 until Facebook gives 60 days' notice for ending the Transition Period or until you upgrade to Audience Network SDK v5.10 or higher, whichever is sooner.

Learn more about Data Processing Options:

Reference

FieldDescription

Data Processing Options

type: array

Processing options you would like to enable for a specific event. Current accepted value is LDU for Limited Data Use.


The name of this field can be presented differently, depending on the API and implementation you are using. For example, this is dataProcessingOptions for a Pixel JavaScript call, but data_processing_options for a Conversions API call. Please see the example calls below.


An empty array can be sent to explicitly specify that this event shouldn't be processed with the Limited Data Use restrictions.

Data Processing Options Country

type: integer

Optional for most APIs. See note below for details.


A country that you want to associate to this data processing option. Current accepted values are 1, for the United States of America, or 0, to request that we geolocate that event.


Notes:

  • This field is required for Offline Conversions during the Transition Period stated above or if you send LDU under data_processing_options.
  • This field is required for Conversions API if you do not provide an IP address during the Transition Period stated above or if you send LDU under data_processing_options.

Data Processing Options State

type: integer

Optional for most APIs. See note below for details.


A state that you want to associate to this data processing option. Current accepted values are 1000, for California, or 0, to request that we geolocate that event.


Notes:

  • If you set a country, you must also set a state. Otherwise, we apply our geolocation logic to the entire event.
  • This field is required for Offline Conversions during the Transition Period stated above, if you send LDU under data_processing_options. Note that geolocation is currently unavailable for this API.
  • This field is required for Conversions API during the Transition Period stated above, if you send LDU under data_processing_options and do not provide an IP address.

This feature is rolling out to the latest SDKs and may not be available immediately.

Supported Tools and APIs

Pixel

ImplementationAdding Data Processing Options

Browser Pixel

Update Pixel initialization code to specify the dataProcessingOptions method before you call fbq('init').


To explicitly not enable Limited Data Use (LDU) mode, use:

fbq('dataProcessingOptions', []);
fbq('init', '{pixel_id}');
fbq('track', 'PageView');

To enable LDU mode using geolocation, use:

fbq('dataProcessingOptions', ['LDU'], 0, 0);

To enable LDU for users and specify user geography:

fbq('dataProcessingOptions', ['LDU'], 1, 1000);

Image tag

Add the following to the Pixel image tag:

  • dpo: data processing options
  • dpoco: data processing options country
  • dpost: data processing options state

See Reference for accepted values.


To explicitly not enable LDU mode, pass an empty value for the 'dpo' parameter:

<img src="https://www.facebook.com/tr?id={pixel_id}&ev=Purchase&dpo=" />

To enable LDU with geolocation:

<img src="https://www.facebook.com/tr?id={pixel_id}&ev=Purchase&dpo=LDU&dpoco=0&dpost=0" />

To enable LDU and specify user geography:

<img src="https://www.facebook.com/tr?id={pixel_id}&ev=Purchase&dpo=LDU&dpoco=1&dpost=1000" />

Conversions API and Offline Conversions API

For these two APIs, implement data processing options by adding data_processing_options, data_processing_options_country, and data_processing_options_state inside each event within the data parameter of your events.

To explicitly not enable Limited Data Use (LDU) mode, specify an empty array for each event: 
{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": []
        }
    ]
}
To enable LDU and specify user geography: 
{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 1,
            "data_processing_options_state": 1000
        }
    ]
}
To enable LDU with geolocation (this works for Server-side API provided client IP address is provided): 
{
    "data": [
        {
            "event_name": "Purchase",
            "event_time": <EVENT_TIME>,
            "user_data": {
                "em": "<EMAIL>",
                "client_ip_address": "256.256.256.256"
            },
            "custom_data": {
                "currency": "<CURRENCY>",
                "value": "<VALUE>"
            },
            "data_processing_options": ["LDU"],
            "data_processing_options_country": 0,
            "data_processing_options_state": 0
        }
    ]
}

Manual Upload UI

The Offline Conversions API offers the option to manually upload your events from a .csv file. In this case, add Data Processing Options, Data Processing Country, and Data Processing State as columns inside your file. More information about this can be found in the upload user interface.

Offline Conversions Automated Uploader

App Events API

If you are calling the App Events API and not sending data directly from user devices, you must either send the client IP address using the HTTP X-Forwarded-For header, or explicitly specify the geography.

Graph API

To implement Data Processing Options using the Graph API, add data_processing_options, data_processing_options_country, and data_processing_options_state to your API call. To explicitly not enable LDU mode, send an empty data_processing_options array: 
{
  "event": "CUSTOM_APP_EVENTS",
  "application_tracking_enabled": "1",
  "advertiser_tracking_enabled": "1",
  "custom_events": ["fb_mobile_purchase"],
  "data_processing_options": []
}
To enable LDU for users with geolocation, you can send an event with the following code: 
{
  "event": "CUSTOM_APP_EVENTS",
  "application_tracking_enabled": "1",
  "advertiser_tracking_enabled": "1",
  "custom_events": ["fb_mobile_purchase"],
  "data_processing_options": ["LDU"],
  "data_processing_options_country": 0,
  "data_processing_options_state": 0
}
To enable LDU for users and specify user geography, you can send an event with the following code: 
  {
  "event": "CUSTOM_APP_EVENTS",
  "application_tracking_enabled": "1",
  "advertiser_tracking_enabled": "1",
  "custom_events": ["fb_mobile_purchase"],
  "data_processing_options": ["LDU"],
  "data_processing_options_country": 1,
  "data_processing_options_state": 1000
}

Mobile SDKs

ImplementationAdding Data Processing Options

Facebook SDK for iOS (Objective C)

With Objective C, use FBSDKSettings setDataProcessingOptions.


To explicitly not enable Limited Data Use (LDU) mode, use:

[FBSDKSettings setDataProcessingOptions:@[]];

To enable LDU with geolocation, use:

[FBSDKSettings setDataProcessingOptions:@[@"LDU"] country:0 state:0];

To enable LDU for users and specify user geography, use:

[FBSDKSettings setDataProcessingOptions:@[@"LDU"] country:1 state:1000];

Facebook SDK for iOS (Swift)

With Swift, use setDataProcessingOptions.


To explicitly not enable LDU mode, use:

Settings.setDataProcessingOptions(modes: [])

To enable LDU for users with geolocation, use:

Settings.setDataProcessingOptions(modes: ["LDU"], country: 0, state: 0)

To enable LDU for users and specify user geography, use:

Settings.setDataProcessingOptions(modes: ["LDU"], country: 1, state: 1000)

Facebook SDK for Android

Use the setDataProcessingOptions method.


To explicitly not enable LDU mode, use:

FacebookSdk.setDataProcessingOptions(new String[] {});

To enable LDU for users with geolocation, use:

FacebookSdk.setDataProcessingOptions(new String[] {"LDU"}, 0, 0);

To enable LDU for users with a specified geography, use:

FacebookSdk.setDataProcessingOptions(new String[] {"LDU"}, 1, 1000);

Unity SDK

To explicitly not enable LDU mode, send an event with:

FB.Mobile.SetDataProcessingOptions(new string[] {});

To enable LDU for users with geolocation, send an event with:

FB.Mobile.SetDataProcessingOptions(new string[] {"LDU"}, 0, 0);

To enable LDU for users and specify user geography, send an event with:

FB.Mobile.SetDataProcessingOptions(new string[] {"LDU"}, 1, 1000);

Audience Network SDK

Publishers who upgrade to Audience Network SDK version 5.10 or higher, must set the Limited Data Use flag in order for Facebook to continue to apply restrictions to personal information they share about people in California.

ImplementationAdding Data Processing Options

Facebook SDK for iOS, v5.10+

Use FBAdSettings setDataProcessingOptions.


To explicitly not enable Limited Data Use (LDU) mode, use:

[FBAdSettings setDataProcessingOptions:@[]];

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:1 state:1000];

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:0 state:0];

Facebook SDK for Android, v5.10+

Use the setDataProcessingOptions method.


To explicitly not enable LDU mode, use:

AdSettings.setDataProcessingOptions(new String[] {})

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 1, 1000);

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 0, 0);

Unity SDK, v5.10+ (not using the Audience Network-supplied Unity wrapper)

If you are not using the Audience Network-supplied Unity wrapper, enter the following code.


            using UnityEngine;
            using System.Runtime.InteropServices;

            namespace AudienceNetwork
            {
            public static class AdSettings
            {

            public static void SetDataProcessingOptions(string[] dataProcessingOptions)
            {
            #if UNITY_ANDROID
            AndroidJavaClass adSettings = new AndroidJavaClass("com.facebook.ads.AdSettings");
            adSettings.CallStatic("setDataProcessingOptions", (object)dataProcessingOptions);
            #endif

            #if UNITY_IOS
            FBAdSettingsBridgeSetDataProcessingOptions(dataProcessingOptions, dataProcessingOptions.Length);
            #endif
            }

            public static void SetDataProcessingOptions(string[] dataProcessingOptions, int country, int state)
            {
            #if UNITY_ANDROID
            AndroidJavaClass adSettings = new AndroidJavaClass("com.facebook.ads.AdSettings");
            adSettings.CallStatic("setDataProcessingOptions", (object)dataProcessingOptions, country, state);
            #endif

            #if UNITY_IOS
            FBAdSettingsBridgeSetDetailedDataProcessingOptions(dataProcessingOptions, dataProcessingOptions.Length, country, state);
            #endif
            }

            #if UNITY_IOS
            [DllImport("__Internal")]
            private static extern void FBAdSettingsBridgeSetDataProcessingOptions(string[] dataProcessingOptions, int length);

            [DllImport("__Internal")]
            private static extern void FBAdSettingsBridgeSetDetailedDataProcessingOptions(string[] dataProcessingOptions, int length, int country, int state);
            #endif
            }
            }

After entering this code, you can follow the Unity SDK instructions in the row below as if you are using the Unity wrapper.

Unity SDK, v5.10+ (using the Audience Network-supplied Unity wrapper)

If you are using the Audience Network-supplied Unity wrapper, use the following SetDataProcessingOptions.


To explicitly not enable LDU mode, use:

AdSettings.SetDataProcessingOptions(new string[]{})

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
AdSettings.SetDataProcessingOptions(new string[] {"LDU"}, 1, 1000);

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
AdSettings.SetDataProcessingOptions(new string[] {"LDU"}, 0, 0);

Publishers using a Mediation Partner must set the Data Processing Options (Limited Data Use) flag on the Facebook Audience Network SDK before initializing the Mediation SDK so that it is received by us in the bidding request.

ImplementationAdding Data Processing Options

Android

To explicitly not enable LDU mode, use:

AdSettings.setDataProcessingOptions(new String[] {})

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 1, 1000);

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 0, 0);

After setting the LDU flag, initialize mediation partner SDK as per usual.

iOS

To explicitly not enable Limited Data Use (LDU) mode, use:

FBAdSettings setDataProcessingOptions:@[]];

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:1 state:1000];

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:0 state:0];

After setting the LDU flag, initialize mediation partner SDK as per usual.

For publishers that are working with us through Bidding Kit and other Server-side Bidding, please follow the implementation methods below.

ImplementationAdding Data Processing Options

Android/Bidding Kit 2.0

To explicitly not enable LDU mode, use:

AdSettings.setDataProcessingOptions(new String[] {})

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 1, 1000);

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 0, 0);

After setting the LDU flag, generate the bidder token:

String token = BidderTokenProvider.getBidderToken(Context);

iOS/Bidding Kit 2.0

To explicitly not enable Limited Data Use (LDU) mode, use:

[FBAdSettings setDataProcessingOptions:@[]];

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:1 state:1000];

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:0 state:0];

After setting the LDU flag, generate the bidder token:

NSString *token = [FBAdSettings bidderToken];

Other Server-Side Bidding

For each platform follow the instructions below to set the LDU flag and retrieve the bidder token before making the server-side bid request.


For Android client:

To explicitly not enable LDU mode, use:

AdSettings.setDataProcessingOptions(new String[] {})

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 1, 1000);

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
AdSettings.setDataProcessingOptions(new String[] {"LDU"}, 0, 0);

After setting the LDU flag, generate the bidder token:

String token = BidderTokenProvider.getBidderToken(Context);

For iOS client:

To explicitly not enable Limited Data Use (LDU) mode, use:

[FBAdSettings setDataProcessingOptions:@[]];

To enable LDU for users and specify user geography, use:

  • Country: 1 to indicate USA
  • State: 1000 to indicate California.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:1 state:1000];

To enable LDU for users with geolocation, use:

  • Country: 0 to request that we geolocate that event
  • State: 0 to request that we geolocate that event.
[FBAdSettings setDataProcessingOptions:@[@"LDU"] country:0 state:0];

After setting the LDU flag, generate the bidder token:

NSString *token = [FBAdSettings bidderToken];

For AN SDK version below 5.10, businesses can override the automatic application of the Limited Data Use restrictions period through a setting in Monetization Manager. Please note, this override setting would only apply whenever a request relating to a person in California does not have a 'Limited data use' flag (i.e. any request coming from AN SDK versions below 5.10).