Remote Command: Facebook
Requirements
- One of these mobile libraries:
- Tealium for Android-Kotlin (1.0.0+)
- Tealium for Android-Java (5.9.0+ for Facebook 1.0.0+ or <5.9.0 for previous versions)
- Tealium for iOS-Swift
- One of these remote command integrations:
- Facebook Remote Command JSON File (Requires Android-Kotlin 1.0.0+ or iOS-Swift 2.1.0+)
- 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 Facebook integration uses three items:
- The Facebook native SDK
- The remote commands module that wraps the Facebook methods
- 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 CocoaPods:
Remove
tealium-swift
andpod "FBSDKCoreKit"
if they already exist your Podfile. The dependency fortealium-swift
is already included in theTealiumFacebook
framework.Add the following dependency to your Podfile:
pod "TealiumFacebook"
The
TealiumFacebook
pod includes the followingTealiumSwift
dependencies:'tealium-swift/Core' 'tealium-swift/TealiumDelegate' 'tealium-swift/TealiumRemoteCommands' 'tealium-swift/TealiumTagManagement'
Import the modules
TealiumSwift
andTealiumFacebook
in yourTealiumHelper
file, and any other files that access theTealium
class, or the Facebook Remote Command.
To install Facebook remote commands for iOS using Carthage:
Remove
tealium-swift
from your Cartfile. The dependency fortealium-swift
is already included in theTealiumFacebook
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 the Tealium for Swift library 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.Add
Dispatchers.RemoteCommands
as a dispatcherSet the
remoteAPIEnabled
configuration flag totrue
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:
Add
flatDir
to your project rootbuild.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.
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:
In the
TealiumHelper.swift
file, initialize an empty array of objects that conform to theTealiumRegistration
protocol. For example:var pushMessagingHelpers = [TealiumRegistration]()
Initialize the
FacebookInstance
before theFacebookRemoteCommand
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.
- 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 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.