Remote Command: Facebook | Integrations |Tealium Developer Docs

Requirements

Tealium for Android or Tealium for iOS in your app
Facebook Remote Command Tag in Tealium iQ Tag Management

The following are requirements for iOS and Android:

The following AndroidManifest.xml keys are required for Android:

<string name="facebook_app_id">[APP_ID]</string>
<string name="fb_login_protocol_scheme">fb[APP_ID]</string>

Learn more: Facebook Android Getting Started - Integrate the Facebook SDK in Your Android App

The following keys are required in the .plist file for iOS:

<key>CFBundleURLTypes</key>
<array>
  <dict>
  <key>CFBundleURLSchemes</key>
  <array>
    <string>fb[APP_ID]</string>
  </array>
  </dict>
</array>
<key>FacebookAppID</key>
<string>[APP_ID]</string>
<key>FacebookDisplayName</key>
<string>[APP_NAME]</string>

Learn more: Facebook iOS Getting Started - Configure Your Property List

Update the AppDelegate code as follows:

Import FBSDKCoreKit

In the didFinishLaunchingWithOptions method add the following:

FBSDKApplicationDelegate.sharedInstance().application(
  application,
  didFinishLaunchingWithOptions: launchOptions)

Add the following function in your AppDelegate.swift (or Objective-C equivalent)

func application(
   _ app: UIApplication,
  open url: URL,
  options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
let handled = FBSDKApplicationDelegate.sharedInstance().application(
  app,
  open: url,
  options: options)

Learn more: Facebook iOS Getting Started - Set Up Your Development Environment

How It Works

The integration with Facebook uses the native Facebook SDK, a remote commands module that wraps the Facebook methods, and the Facebook Remote Command tag that translates event tracking into native Facebook calls. This solution leverages the convenience of Tealium iQ Tag Management to configure a native Facebook implementation without having to add vendor-specific code to your app.

Adding the Facebook remote command module to your app automatically installs and builds the required Facebook libraries. If you are using a dependency manager installation, there is no need to install the Facebook SDK separately.

Install

Dependency Manager

We recommend using one of the following dependency managers for installation:

If you are using the Tealium iOS (Objective-C) library, use the manual installation method. The CocoaPods and Carthage options are only available if you are using the Tealium iOS (Swift) library.

To install Facebook remote commands for iOS using CocoaPods:

Remove tealium-swift and pod "FBSDKCoreKit" if they already exist your Podfile. The dependency for tealium-swift is already included in the TealiumFacebook framework.

Add the following dependency to your Podfile:

pod "TealiumFacebook"

The TealiumFacebook pod includes the following TealiumSwift dependencies:

'tealium-swift/Core'
'tealium-swift/TealiumDelegate'
'tealium-swift/TealiumRemoteCommands'
'tealium-swift/TealiumTagManagement'

Add any other required modules manually to your Podfile, such as the following:
```
'tealium-swift/TealiumLogger'
'tealium-swift/TealiumLifecycle'
'tealium-swift/TealiumAppData'
```
Learn more about the recommended modules for iOS.
Import the modules TealiumSwift and TealiumFacebook in your TealiumHelper file, and any other files that access the Tealium class, or the Facebook Remote Command.

To install Facebook remote commands for iOS using Carthage:

Remove tealium-swift from your Cartfile. The dependency for tealium-swift is already included in the TealiumFacebook framework.
Remove the following line if it exists in your Cartfile:
```
github "facebook/facebook-ios-sdk"
```

Add the following dependency to your Cartfile:

github "tealium/tealium-ios-facebook-remote-command"

Tealium for Swift SDK (version 1.6.5+) requires the TealiumDelegate module to be included with your installation.

To install Facebook remote commands for Android using Maven:

Install Tealium’s Android SDK, if you haven’t done so already.

Add the Tealium Maven URL to your project’s top-level build.gradle file:

allprojects {
repositories {
jcenter()
maven {
  url "https://maven.tealiumiq.com/android/releases/"
}
}
}

Import both the Facebook SDK and Tealium-Facebook remote commands by adding the following dependencies in your app project’s build.gradle file:
```
dependencies {
  implementation 'com.tealium.remotecommands:facebook:1.0.0'
}
```

Manual (iOS)

The manual installation for Facebook remote commands requires one of the following iOS libraries to be installed:

To install the Facebook remote commands for your iOS project:

Install the Facebook SDK, if you haven’t already done so.
Clone the Tealium iOS Facebook remote command repo and drag the files within the Sources folder into your project.

When initializing the Tealium Swift SDK, in the completion handler:

tealium = Tealium(config: config) { responses in
  guard let remoteCommands = self.tealium?.remoteCommands() else {
    return
  }
  let facebookRemoteCommand = FacebookRemoteCommand().remoteCommand()
  remoteCommands.add(facebookRemoteCommand)
}

If you are using the TealiumIOS, add the following code:

Add the remote command in the TealiumHelper.swift file as follows:

let facebookTracker = FacebookTracker()
let facebookRemoteCommand = FacebookRemoteCommand(facebookTracker: facebookTracker).remoteCommand()
tealium.addRemoteCommandID("facebook",
                           description: nil,
                           targetQueue: DispatchQueue.main,
                           responseBlock: facebookRemoteCommand)

Import the remote command in the TealiumHelper.m file as follows:

#import "TealiumRemoteCommandObjcApp-Swift.h"

The Swift bridging header for your target is named ending with -Swift.h. Find this by filtering for “Module Name” in your target’s build settings.

Learn more about importing Swift into Objective-C.

Initialize the remote command as follows:

FacebookTracker *facebookTracker = [[FacebookTracker alloc] init];
FacebookRemoteCommand *facebookRemoteCommand = [[FacebookRemoteCommand alloc] initWithFacebookTracker: facebookTracker];
TEALRemoteCommandResponseBlock facebookRemoteCommandResponse = [facebookRemoteCommand remoteCommand];
[[Tealium instanceForKey:@"MY_INSTANCE"] addRemoteCommandID:@"facebook"
                                    description:@"Facebook Remote Command"
                                    targetQueue:dispatch_get_main_queue()
                                    responseBlock: facebookRemoteCommandResponse];

Manual (Android)

The manual installation for Facebook remote commands requires the following Android library to be installed:

Tealium for Android

To install the Facebook remote commands for your Android project:

Add flatDir to your project root build.gradle file:

allprojects {
  repositories {
     jcenter()
     flatDir {
         dirs 'libs'
     }
  }
}

Add tealium-facebook.aar to <PROJECT_ROOT>/<MODULE>/libs.

Add the Tealium library dependency to your build.gradle file:

dependencies {
  implementation(name:'tealium-facebook', ext:'aar')
}

Initialize

For all Tealium libraries, register the Facebook Remote Command when you initialize.

The following code is designed for use with Tealium’s Android library:

import com.tealium.remotecommands.facebook.FacebookRemoteCommand;

Tealium.Config config = Tealium.Config.create(application, "ACCOUNT", "PROFILE", "ENVIRONMENT");
Tealium teal = Tealium.createInstance(TEALIUM_MAIN, config);

FacebookRemoteCommand facebook = new FacebookRemoteCommand(this);

// register the command
teal.addRemoteCommand(facebook);

The following code is designed for use with Tealium’s Android library.

import com.tealium.remotecommands.facebook.FacebookRemoteCommand

val config = Tealium.Config.create(this, "ACCOUNT", "PROFILE", "ENVIRONMENT")
tealium = Tealium.createInstance(TealiumHelper.instanceName, config)

val facebook = FacebookRemoteCommand(this)

// register the command
tealium.addRemoteCommand(facebook)

The following code is designed for use with Tealium’s Swift library for iOS:

var teal : Tealium?
let config = TealiumConfig(account: "your_account",
                           profile: "your_profile",
                           environment: "dev",
                           datasource: "abc123",
                           optionalData: nil)

teal = Tealium(config: config) { responses in
  guard let remoteCommands = self.tealium?.remoteCommands() else {
        return
  }
  let facebookRemoteCommand = FacebookRemoteCommand().remoteCommand()
  remoteCommands.add(facebookRemoteCommand)
}

The following code is designed for use with Tealium’s Objective-C library for iOS, although it is written in Swift. A Bridging Header is required in your Xcode project for this code to work correctly.

let config = TEALConfiguration(account: "your_account",
                               profile: "your_profile",
                               environment: "dev",
                               datasource: "abc123")
let teal = Tealium.newInstance(forKey: "teal", configuration: config)

let facebookRemoteCommand = FacebookRemoteCommand().remoteCommand()
teal.addRemoteCommandID("facebook", description: nil, targetQueue: DispatchQueue.main, responseBlock: facebookRemoteCommand)

Push Message Tracking

The Tealium Swift library includes a TealiumRegistration protocol for handling push message tracking via Tealium and the Facebook Remote Command. We conform to this protocol in FacebookTracker and is used to send push message authorization events, push message open events, and to uninstall tracking. We recommend taking advantage of the push message tracking capability.

The following steps integrate push message tracking for your iOS project:

In the TealiumHelper.swift file, initialize an empty array of objects that conform to the TealiumRegistration protocol. For example:
```
var pushMessagingTrackers = [TealiumRegistration]()
```
Initialize the FacebookTracker before the FacebookRemoteCommand
Append the FacebookTracker to the array described above

The following is full example of the push message tracking integration:

var pushMessagingTrackers = [TealiumRegistration]()

//...

teal = Tealium(config: config) { responses in
  guard let remoteCommands = self.tealium?.remoteCommands() else {
        return
  }
  let facebookTracker = FacebookTracker()
  let facebookRemoteCommand = FacebookRemoteCommand(facebookTracker: facebookTracker).remoteCommand()
  remoteCommands.add(facebookRemoteCommand)
  self.pushMessagingTrackers.append(facebookTracker)
}

To see the entire TealiumHelper.swift file, explore the Facebook Remote Command sample apps. To send an event to Facebook once a user has registered for notifications, opened a push message, or uninstalled the app, see the file AppDelegate.swift.

Supported Methods

The following Facebook methods are triggered using a data mapping in the Facebook Remote Command tag using these Tealium commands:

Remote Command	Facebook Method
`setUser`	`setUser()`
`updateUserValue`	`updateUserValue()`
Any of the below event names	`trackEvent()`
logProductItem	`logProductItem()`
`logPurchase`	`logPurchase()`
`flush`	`flush()`
Manually called in `AppDelegate` within `didReceiveRemoteNotification`	`setPushNotificationsDeviceToken()`
Manually called in `AppDelegate` within `didRegisterForRemoteNotificationsWithDeviceToken`	`registerPushToken()`

Push notifications are currently supported only for the iOS remote command.

iOS setPushNotificationsDeviceToken - used for uninstall tracking
iOS logPushNotificationOpen

Standard Event Names

The following is a list of standard event names supported with the logEvent method. If any of the below command names are sent, they are automatically triggered in the Facebook SDK. This is assuming all the required variables are also mapped and defined for that particular event. Learn about recording in-app events.

Remote Command	Facebook Event Name
`achievedLevel`	`FBSDKAppEventNameAchievedLevel`
`addPaymentInfo`	`FBSDKAppEventNameAddedPaymentInfo`
`addToCart`	`FBSDKAppEventNameAddedToCart`
`addToWishlist`	`FBSDKAppEventNameAddedToWishlist`
`completeRegistration`	`FBSDKAppEventNameCompletedRegistration`
`completeTutorial`	`FBSDKAppEventNameCompletedTutorial`
`initiateCheckout`	`FBSDKAppEventNameInitiatedCheckout`
`purchase`	`FBSDKAppEventNamePurchased`
`subscribe`	`FBSDKAppEventNameSubscribe`
`startTrial`	`FBSDKAppEventNameStartTrial`
`rated`	`FBSDKAppEventNameRated`
`searched`	`FBSDKAppEventNameSearched`
`spentCredits`	`FBSDKAppEventNameSpentCredits`
`unlockAchievement`	`FBSDKAppEventNameUnlockedAchievement`
`contentView`	`FBSDKAppEventNameViewedContent`
`logContact`	`FBSDKAppEventNameContact`
`initiateCheckout`	`FBSDKAppEventNameInitiatedCheckout`
`spentCredits`	`FBSDKAppEventNameSpentCredits`
`customizeProduct`	`FBSDKAppEventNameCustomizeProduct`
`donate`	`FBSDKAppEventNameDonate`
`findLocation`	`FBSDKAppEventNameFindLocation`
`schedule`	`FBSDKAppEventNameSchedule`
`submitApplication`	`FBSDKAppEventNameSubmitApplication`
`adImpression`	`FBSDKAppEventNameAdImpression`
`adClick`	`FBSDKAppEventNameAdClick`

Since the Facebook SDK is installed alongside the Tealium SDK, you are able to trigger any native Facebook functionality given the corresponding tag configuration.

Set User

Sets custom user data to associate with all app events. All user data is hashed and used to match Facebook users from this instance of an application. The user data is persisted between application instances.

Event Name	Required	Optional	Type
`setUser`	`user`		`[String: Any]`

User Dictionary Properties	Optional
`em`	`String`
`fn`	`String`
`ln`	`String`
`dob`	`String`
`ge`	`String`
`ct`	`String`
`st`	`String`
`zp`	`String`
`country`	`String`

Update User Value

Updates a user value for a type/key. All user data is hashed and used to match Facebook users from this instance of an application. The user data is persisted between application instances.

Event Name	Required	Optional	Type
`updateUserValue`	`fb_user_value`		`String`
	`fb_user_key`		`String`

Log Product Item

Uploads product catalog product item as an app event.

Event Name	Required	Optional	Type
`logProductItem`	`fb_product_item_id`		`String`
	`fb_product_availability`		`Int` (See lookup below)
	`fb_product_condition`		`Int` (See lookup below)
	`fb_product_description`		`String`
	`fb_product_image_link`		`String`
	`fb_product_link`		`String`
	`fb_product_title`		`String`
	`fb_product_price_amount`		`Double/Decimal`
	`fb_product_price_currency`		`String`
	`fb_product_parameters`		`[String: Any]` - JavaScript Object if in TiQ
		`fb_product_gtin`	`String`
		`fb_product_mpn`	`String`
		`fb_product_brand`	`String`

Either gtin, mpn or brand is required. Product parameters are optional fields for deep link specification.

Product Availability Input	Product Availability Lookup
`0`	In Stock - Item ships immediately
`1`	Out of stock - No plan to restock
`2`	Preorder - Available in future
`3`	Available for order - Ships in 1-2 weeks
`4`	Discontinued - Discontinued

Product Condition Input	Product Condition Lookup
`0`	New
`1`	Refurbished
`2`	Used

Log Purchase

Log a purchase of the specified amount, in the specified currency, also optionally providing a set of additional characteristics describing the purchase.

Arbitrary parameter dictionary of characteristics. The keys to this dictionary must be NSString’s, and the values are expected to be NSString or NSNumber. Limitations on the number of parameters and name construction are given in the FBSDKAppEvents documentation. Commonly used parameter names are provided in FBSDKAppEventParameterName constants.

Event Name	Required	Optional	Type
`logPurchase`	`fb_purchase_amount`		`Decimal/Double` (iOS) / `Double` (Android)
	`fb_purchase_currency`		`String`
		`fb_purchase_parameters`	`[String: Any]` - Javascript object in TiQ

Flush

Explicitly kick off flushing of events to Facebook. This is an asynchronous method, but it does initiate an immediate kick off. Server failures are reported through the NotificationCenter with notification ID FBSDKAppEventsLoggingResultNotification.

Event Name	Required	Optional	Type
`flush`

Log Event

The following are Facebook Standard Events and accept a number of optional parameters in the payload.

achieveLevel
adClick
adImpression
addPaymentInfo
addToCart
addToWishlist
completeRegistration
completeTutorial
logContact
viewedContent
search
rate
customizeProduct
donate
findLocation
schedule
startTrial
submitApplication
subscribe
subscriptionHeartbeat
initiateCheckout
purchase
unlockAchievement
spentCredits

Because the Facebook SDK is installed alongside the Tealium SDK, all native Facebook functionality is available.

Event Name	Required	Optional	Type
	`command_name` (one of the event names listed above)
Any of the event names listed above		See parameters list	Multiple
		`fb_value_to_sum`	`Double/Decimal` (iOS) / `Double` (Android)

Handle Push

Used to measure app uninstalls.

Event Name	Required	Optional	Type
`setPushNotificationsDeviceToken`	`deviceToken`		`Data`

Facebook iOS SDK Integration - setPushNotificationsDeviceToken

If using the Tealium Swift library, see push message tracking to see how to have this handled for you. You also have the option to call this method yourself. This feature is support in the iOS remote command only.

Opened App From Push

Tracks an event when the user has opened the app from a push notification.

Event Name	Required	Optional	Type
`logPushNotificationOpen`	`payload` (userInfo)		`[String: Any]`

Facebook iOS SDK Integration - logPushNotificationOpen