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 Facebook integration uses three items:

    1. The Facebook native SDK
    2. The remote commands module that wraps the Facebook methods
    3. Either the JSON configuration file or Remote Command tag that translates event tracking into native Facebook calls

    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 Swift Package Manager:

      1. In your Xcode project, select File > Swift Packages > Add Package Dependency.
      2. Enter the repository URL: https://github.com/tealium/tealium-ios-facebook-remote-command.
      3. Configure the version rules. Typically, Up to next major is recommended. If the current TealiumFacebook version does not appear in the list, then reset your Swift package cache.
      4. Select the TealiumFacebook module to install and add the modules to each of your app targets in your Xcode project, under Frameworks > Libraries & Embedded Content.

      To add additional modules from the Tealium Swift library, follow the Swift Package Manager instructions.

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

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

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

          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 (iOS)

            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 the wrapper class FacebookInstance which 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 pushMessagingHelpers = [TealiumRegistration]()

            2. Initialize the FacebookInstance before the FacebookRemoteCommand

            3. Append the FacebookInstance to the array described above

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

            var pushMessagingHelpers = [TealiumRegistration]()

//...

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

            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