REMOTE COMMANDS/INTEGRATIONS

Remote Command: Facebook

Requirements

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:

    1. Import FBSDKCoreKit

    2. In the didFinishLaunchingWithOptions method add the following:

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

    3. 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. The integration uses three items:

    1. The Facebook native SDK
    2. The remote commands module
    3. Either the JSON configuration file or Remote Command tag

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

    There are two remote command options: A JSON configuration file, or using iQ Tag Management to configure the mappings. A JSON configuration file is the recommended option for your vendor integration, hosted either remotely or locally within your app. If using iQ Tag Management, add the Remote Command tag for the vendor integration. Learn more about vendor integrations.

    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:

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

      2. 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'

      3. 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.

      4. 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:

      1. Remove tealium-swift from your Cartfile. The dependency for tealium-swift is already included in the TealiumFacebook framework.

      2. Remove the following line if it exists in your Cartfile:

        github "facebook/facebook-ios-sdk"

      3. 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:

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

      2. 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/"
    }
  }
}

      3. 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 the Tealium for Swift library to be installed. To install the Facebook remote commands for your iOS project:

      1. Install the Facebook SDK, if you haven’t already done so.

      2. Clone the Tealium iOS Facebook remote command repo and drag the files within the Sources folder into your project.

      3. Add Dispatchers.RemoteCommands as a dispatcher

      4. Set the remoteAPIEnabled configuration flag to true

      5. When initializing the Tealium SDK, update the completion handler as follows:

        The following code is designed for use with the JSON Remote Commands feature, using the local file option.

        let config = TealiumConfig(account: "ACCOUNT", profile: "PROFILE", environment: "ENVIRONMENT")
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true // Required to use Remote Commands

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }
    let facebook = FacebookRemoteCommand(type: .local(file: "facebook"))
    remoteCommands.add(facebook)
}

        The following code is designed for use with the Remote Command tag feature.

        let config = TealiumConfig(account: "ACCOUNT", profile: "PROFILE", environment: "ENVIRONMENT")
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true // Required to use Remote Commands

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

        Manual (Android)

        The manual installation for Facebook remote commands requires Tealium for Android (Kotlin) or Tealium for Android (Java) to be installed.

        To install the Facebook remote commands for your Android project:

        1. Add flatDir to your project root build.gradle file:

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

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

        3. 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.

        Android (Kotlin)

        Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s Kotlin library.

          The following code is designed for use with the JSON Remote Commands feature, using the local file option:

          val config = TealiumConfig(application, "ACCOUNT", "PROFILE", Environment.DEV, dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
var tealium = Tealium.create(TEALIUM_MAIN, config) {
  val facebook = FacebookRemoteCommand(this);
  // register the command
  remoteCommands?.add(facebook, filename = "facebook.json");
}

          The following code is designed for use with the Remote Command tag feature:

          val config = TealiumConfig(application, "ACCOUNT", "PROFILE", Environment.DEV, dispatchers = mutableSetOf(Dispatchers.RemoteCommands));
var tealium = Tealium.create(TEALIUM_MAIN, config) {
  val facebook = FacebookRemoteCommand(this);
  // register the command
  remoteCommands?.add(facebook);
}

          Android (Java)

            The following code is designed for use with the Remote Command tag feature:

            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 JSON Remote Command file feature for Android is only available in the Kotlin SDK

            iOS (Swift)

            Initialize remote commands with a JSON configuration file or the Remote Command tag for Tealium’s iOS (Swift) library.

              The following code is designed for use with the JSON Remote Commands feature, using the local file option:

              var tealium : Tealium?
let config = TealiumConfig(account: "ACCOUNT",
                           profile: "PROFILE",
                           environment: "ENVIRONMENT",
                           dataSource: "DATASOURCE",
                           optionalData: nil)
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true // Required to use Remote Commands

tealium = Tealium(config: config) { _ in
    guard let remoteCommands = self.tealium?.remoteCommands else {
        return
    }
    let facebook = FacebookRemoteCommand(type: .local(file: "facebook"))
    remoteCommands.add(facebook)
}

              The following code is designed for use with the Remote Command tag feature:

              var tealium : Tealium?
let config = TealiumConfig(account: "ACCOUNT",
                           profile: "PROFILE",
                           environment: "ENVIRONMENT",˜˜
                           dataSource: "DATASOURCE",
                           optionalData: nil)
config.dispatchers = [Dispatchers.TagManagement, Dispatchers.RemoteCommands]
config.remoteAPIEnabled = true // Required to use Remote Commands

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

              JSON Template

              If you are configuring remote commands using a JSON configuration file, refer to the following template to get started. The template includes common mappings used in a standard e-commerce installation. Edit the mappings as needed.

              {
  "config": {
    "applicationid": "YOUR_APP_ID",
    "accesstoken": "YOUR_ACCESS_TOKEN",
    "userid": "YOUR_USER_ID",
    "auto_log_events_enabled": true,
    "auto_init_enabled": true,
    "advertiser_id_collection_enabled": true,
    "debug": true
  },
  "mappings": {
    "achievement_type": "event.fb_description",
    "ad_type": "event.ad_type",
    "content": "event.fb_content",
    "content_type": "event.fb_content_type",
    "currency_cod": "event.fb_currency",
    "event_name": "event.fb_description",
    "current_level": "event.fb_level",
    "pet_count": "event.fb_max_rating_value",
    "number_of_items": "event.fb_num_items",
    "order_id": "event.fb_order_id",
    "payment_info_available": "event.fb_payment_info_available",
    "signup_method": "event.fb_registration_method",
    "search_keyword": "event.fb_search_string",
    "success": "event.fb_success",
    "customer_email": "user.em",
    "customer_first_name": "user.fn",
    "customer_last_name": "user.ln",
    "customer_phone": "user.ph",
    "customer_dob": "user.dob",
    "customer_gender": "user.ge",
    "customer_city": "user.ct",
    "customer_state": "user.st",
    "customer_zip": "user.zp",
    "customer_country": "user.country",
    "customer_id": "fb_user_id",
    "user_value": "fb_user_value",
    "user_key": "fb_user_key",
    "product_id": "product.fb_product_item_id,event.fb_content_id",
    "product_availability": "product.fb_product_availability",
    "product_condition": "product.fb_product_condition",
    "product_description": "product.fb_product_description,event.fb_product_description",
    "product_image_link": "product.fb_product_image_link",
    "product_link": "product.fb_product_link",
    "product_name": "product.fb_product_title",
    "product_variant": "product.fb_product_gtin",
    "product_brand": "product.fb_product_brand",
    "product_price": "product.fb_product_price_amount,event.fb_value_to_sum",
    "product_currency": "product.fb_product_price_currency",
    "product_alias": "product_parameters.product_alias",
    "product_color": "product_parameters.product_color",
    "order_total": "purchase.fb_purchase_amount",
    "order_currency": "purchase.fb_purchase_currency",
    "customer_status": "purchase_parameters.customer_status",
    "coupon": "purchase_parameters.coupon",
    "push_action": "push.fb_push_action",
    "push_payload": "push.fb_push_payload",
    "tealium_event": "command_name"
  },
  "commands": {
    "launch": "initialize,setautologappeventsenabled,setautoinitenabled,enableadvertiseridcollection",
    "user_login": "setuser,setuserid",
    "email_signup": "updateuservalue",
    "level_up": "achievedlevel",
    "user_register": "completedregistration",
    "unlock_achievement": "unlockedachievment",
    "cart_add": "addedtocart",
    "custom_attribute": "rated",
    "wishlist_add": "addedtowishlist",
    "payment": "initiatedcheckout",
    "product": "logproductitem",
    "order": "logpurchase",
    "flush": "flush"
  }
}

              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:

              1. In the TealiumHelper.swift file, initialize an empty array of objects that conform to the TealiumRegistration protocol. For example:

                var pushMessagingTrackers = [TealiumRegistration]()

              2. Initialize the FacebookTracker before the FacebookRemoteCommand

              3. 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.

              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 iQ
              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 iQ

              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.

              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
              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

              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]

              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.

              Remote Command: Contentsquare
              Remote Command: Firebase