Settings

Configure Facebook SDK settings and behavior

The Settings module provides methods to configure the Facebook SDK, including app credentials, API versions, data collection, and privacy settings.

Import

import { Settings } from 'react-native-fbsdk-next';

Methods

initializeSDK

Initializes the Facebook SDK. This should be called early in your app lifecycle.

Settings.initializeSDK(): void

Example:

import { Settings } from 'react-native-fbsdk-next';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    Settings.initializeSDK();
  }, []);

  return (
    // Your app content
  );
}

setAppID

Sets your Facebook application ID.

Settings.setAppID(appID: string): void

appID · string · required

Your Facebook App ID. Must be a non-empty string.

Example:

Settings.setAppID('1234567890123456');

setClientToken

Sets your Facebook client token for client-side API calls.

Settings.setClientToken(clientToken: string): void

clientToken · string · required

Your Facebook client token. Must be a non-empty string.

Example:

Settings.setClientToken('a1b2c3d4e5f6g7h8i9j0');

setAppName

Sets the Facebook application name.

Settings.setAppName(appName: string): void

appName · string · required

Your app’s name as registered on Facebook. Must be a non-empty string.

Example:

Settings.setAppName('My Awesome App');

setGraphAPIVersion

Sets the Graph API version to use for all requests.

Settings.setGraphAPIVersion(version: string): void

version · string · required

The Graph API version (e.g., “v18.0”, “v19.0”). Must be a valid version string.

Example:

Settings.setGraphAPIVersion('v18.0');

setAutoLogAppEventsEnabled

Enables or disables automatic app event logging.

Settings.setAutoLogAppEventsEnabled(enabled: boolean): void

enabled · boolean · required

true to enable automatic logging of app events (installs, launches, etc.), false to disable.

Example:

// Enable automatic event logging
Settings.setAutoLogAppEventsEnabled(true);

// Disable automatic event logging
Settings.setAutoLogAppEventsEnabled(false);

setAdvertiserIDCollectionEnabled

Enables or disables automatic collection of advertiser IDs.

Settings.setAdvertiserIDCollectionEnabled(enabled: boolean): void

enabled · boolean · required

true to collect advertiser IDs (IDFA on iOS, Advertising ID on Android), false to disable.

Example:

// Enable advertiser ID collection
Settings.setAdvertiserIDCollectionEnabled(true);

// Disable advertiser ID collection
Settings.setAdvertiserIDCollectionEnabled(false);

setDataProcessingOptions

Configures data processing options for privacy compliance (e.g., CCPA).

Settings.setDataProcessingOptions(
  options: Array<string>,
  country?: number,
  state?: number
): void

options · Array<string> · required

Array of data processing options. Use ['LDU'] for Limited Data Use mode, or [] for normal processing.

country · number

Country code (0 for user’s current country). Defaults to 0.

state · number

State code (0 for user’s current state). Defaults to 0.

Example:

// Enable Limited Data Use mode
Settings.setDataProcessingOptions(['LDU'], 0, 0);

// Disable Limited Data Use mode
Settings.setDataProcessingOptions([], 0, 0);

// Specify California (country 1, state 1000)
Settings.setDataProcessingOptions(['LDU'], 1, 1000);

getAdvertiserTrackingEnabled

Gets the current Advertiser Tracking Enabled status. iOS only.

Settings.getAdvertiserTrackingEnabled(): Promise<boolean>

Returns a Promise that resolves to:

• true if tracking is enabled (iOS)
• true on Android (always enabled)

Example:

const trackingEnabled = await Settings.getAdvertiserTrackingEnabled();
console.log('Tracking enabled:', trackingEnabled);

setAdvertiserTrackingEnabled

Sets the Advertiser Tracking Enabled status. iOS 14+ only.

Settings.setAdvertiserTrackingEnabled(ATE: boolean): Promise<boolean>

ATE · boolean · required

true to enable tracking, false to disable.

Returns a Promise that resolves to:

• true if the setting was applied successfully (iOS 14+)
• false on Android or iOS < 14

Example:

if (Platform.OS === 'ios') {
  const success = await Settings.setAdvertiserTrackingEnabled(true);
  console.log('Set tracking status:', success);
}

Complete Setup Example

import { useEffect } from 'react';
import { Platform } from 'react-native';
import { Settings } from 'react-native-fbsdk-next';

function App() {
  useEffect(() => {
    // Configure SDK settings
    Settings.setAppID('1234567890123456');
    Settings.setClientToken('a1b2c3d4e5f6g7h8i9j0');
    Settings.setAppName('My Awesome App');
    Settings.setGraphAPIVersion('v18.0');

    // Configure privacy settings
    Settings.setAutoLogAppEventsEnabled(true);
    Settings.setAdvertiserIDCollectionEnabled(true);

    // Initialize SDK
    Settings.initializeSDK();

    // iOS-specific tracking setup
    if (Platform.OS === 'ios') {
      checkTrackingPermission();
    }
  }, []);

  const checkTrackingPermission = async () => {
    const isEnabled = await Settings.getAdvertiserTrackingEnabled();
    console.log('Tracking enabled:', isEnabled);
  };

  return (
    // Your app content
  );
}

Privacy-Compliant Setup

import { useEffect, useState } from 'react';
import { Settings } from 'react-native-fbsdk-next';

function App() {
  const [userConsent, setUserConsent] = useState(false);

  useEffect(() => {
    // Basic setup (always required)
    Settings.setAppID('1234567890123456');
    Settings.setClientToken('a1b2c3d4e5f6g7h8i9j0');
    Settings.setAppName('My Awesome App');
    Settings.setGraphAPIVersion('v18.0');

    // Disable data collection by default
    Settings.setAutoLogAppEventsEnabled(false);
    Settings.setAdvertiserIDCollectionEnabled(false);

    // Enable Limited Data Use for CCPA compliance
    Settings.setDataProcessingOptions(['LDU'], 0, 0);

    Settings.initializeSDK();
  }, []);

  const handleUserConsent = async (consent: boolean) => {
    setUserConsent(consent);

    if (consent) {
      // User granted consent - enable tracking
      Settings.setAutoLogAppEventsEnabled(true);
      Settings.setAdvertiserIDCollectionEnabled(true);
      Settings.setDataProcessingOptions([], 0, 0);
      
      if (Platform.OS === 'ios') {
        await Settings.setAdvertiserTrackingEnabled(true);
      }
    } else {
      // User denied consent - keep limited data mode
      Settings.setAutoLogAppEventsEnabled(false);
      Settings.setAdvertiserIDCollectionEnabled(false);
      Settings.setDataProcessingOptions(['LDU'], 0, 0);
    }
  };

  return (
    // Your app with consent dialog
  );
}

Configuration by Environment

import { Settings } from 'react-native-fbsdk-next';

const CONFIG = {
  development: {
    appID: '1234567890123456',
    clientToken: 'dev_token',
    appName: 'My App (Dev)',
  },
  production: {
    appID: '9876543210987654',
    clientToken: 'prod_token',
    appName: 'My App',
  },
};

const environment = __DEV__ ? 'development' : 'production';
const config = CONFIG[environment];

Settings.setAppID(config.appID);
Settings.setClientToken(config.clientToken);
Settings.setAppName(config.appName);
Settings.setGraphAPIVersion('v18.0');
Settings.initializeSDK();

iOS 14+ ATT Integration

import { useEffect } from 'react';
import { Platform, Alert } from 'react-native';
import { Settings } from 'react-native-fbsdk-next';
import { requestTrackingPermission } from 'react-native-tracking-transparency';

function App() {
  useEffect(() => {
    setupFacebookSDK();
  }, []);

  const setupFacebookSDK = async () => {
    // Configure SDK
    Settings.setAppID('1234567890123456');
    Settings.setClientToken('a1b2c3d4e5f6g7h8i9j0');
    Settings.setGraphAPIVersion('v18.0');

    if (Platform.OS === 'ios') {
      // Request ATT permission first
      const trackingStatus = await requestTrackingPermission();
      
      if (trackingStatus === 'authorized') {
        Settings.setAdvertiserIDCollectionEnabled(true);
        await Settings.setAdvertiserTrackingEnabled(true);
      } else {
        Settings.setAdvertiserIDCollectionEnabled(false);
        await Settings.setAdvertiserTrackingEnabled(false);
      }
    }

    Settings.initializeSDK();
  };

  return (
    // Your app content
  );
}

CCPA Compliance

import { Settings } from 'react-native-fbsdk-next';

// User is in California and opts out
const handleCCPAOptOut = () => {
  Settings.setDataProcessingOptions(['LDU'], 1, 1000); // Country 1 = USA, State 1000 = California
};

// User is in California and opts in
const handleCCPAOptIn = () => {
  Settings.setDataProcessingOptions([], 1, 1000);
};

// Let Facebook detect user's location
const handleAutomaticDetection = () => {
  Settings.setDataProcessingOptions(['LDU'], 0, 0);
};

Best Practices

1. Call initializeSDK() early in your app lifecycle
2. Set app credentials before initializing
3. Specify Graph API version explicitly for consistency
4. Respect user privacy choices for data collection
5. Handle platform differences (iOS vs Android)
6. Test privacy settings in both enabled and disabled states
7. Keep SDK updated to the latest version
8. Use environment-specific configs for dev/prod

Platform Differences

iOS

• Full ATT framework support
• getAdvertiserTrackingEnabled() returns actual status
• setAdvertiserTrackingEnabled() works on iOS 14+

Android

• getAdvertiserTrackingEnabled() always returns true
• setAdvertiserTrackingEnabled() returns false (no-op)
• Advertiser ID controlled by user’s system settings

Related

• AppEventsLogger - Log app events and user actions
• AEMReporter - iOS privacy-safe event measurement
• Facebook App Dashboard - Get your App ID and Client Token
• Graph API Versions - API version changelog