Sitecore Federated Experience Manager Developer's Guide Rev: 21 February 2015
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Sitecore Federated Experience Manager
Developer's Guide A developer's guide to extending and customizing Federated Experience Manager
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 2 of 23
Table of Contents
Chapter 1 Overview ................................................................................................................................... 4 1.1 Capabilities .................................................................................................................................... 5
1.1.1 Tracking External Sites ............................................................................................................. 5 1.1.2 Personalizing External Sites ..................................................................................................... 5 1.1.3 Tracking External Applications .................................................................................................. 5
Chapter 2 Conditions & Actions ................................................................................................................. 6 2.1 FXM Analytics ............................................................................................................................... 7
2.1.1 Custom Conditions .................................................................................................................... 7 2.1.2 Custom Actions ......................................................................................................................... 7
2.2 FXM Content Tracking .................................................................................................................. 8 2.2.1 Custom Conditions .................................................................................................................... 8 2.2.2 Custom Actions ......................................................................................................................... 8 2.2.3 Apply Tracking Action Base ...................................................................................................... 8
2.3 FXM Page ..................................................................................................................................... 9 2.3.1 Custom Conditions .................................................................................................................... 9 2.3.2 Custom Actions ......................................................................................................................... 9
2.4 FXM Template Definition ............................................................................................................. 10 2.4.1 Custom Conditions .................................................................................................................. 10 2.4.2 Custom Actions ....................................................................................................................... 10
2.5 FXM Tracking .............................................................................................................................. 11 2.5.1 Custom Conditions .................................................................................................................. 11 2.5.2 Custom Actions ....................................................................................................................... 11
2.6 FXM Tracking Configuration ....................................................................................................... 12 2.6.1 Custom Conditions .................................................................................................................. 12 2.6.2 Custom Actions ....................................................................................................................... 12
2.7 FXM Web Crawling ..................................................................................................................... 13 2.7.1 Custom Conditions .................................................................................................................. 13 2.7.2 Custom Actions ....................................................................................................................... 13
2.8 Rule Context Types ..................................................................................................................... 14 2.8.1 Web Rule Context ................................................................................................................... 14 2.8.2 Crawling Context ..................................................................................................................... 14 2.8.3 Event Tracking Context ........................................................................................................... 14 2.8.4 Tracking Rule Context ............................................................................................................. 15
Chapter 3 Extending Components ........................................................................................................... 16 3.1 Crawlers ...................................................................................................................................... 17
3.1.1 Interface: IWebCrawler ........................................................................................................... 17 3.2 Event Parsers .............................................................................................................................. 18
3.2.1 Interface: ISingleEventParser ................................................................................................. 18 3.2.2 Interface: IMultiEventParser .................................................................................................... 18
3.3 Event Processors ........................................................................................................................ 19 3.3.1 Interface: IEventProcessor ...................................................................................................... 19
3.4 Language Resolvers ................................................................................................................... 20 3.4.1 Interface: ILanguageResolver ................................................................................................. 20
3.5 Parameter Readers ..................................................................................................................... 21 3.5.1 Interface: IParametersReader ................................................................................................. 21
3.6 Placeholder Selectors ................................................................................................................. 22 3.6.1 Mirror Provider ......................................................................................................................... 22 3.6.2 Method: GetPlaceholderSelectors .......................................................................................... 22
3.7 Site Resolvers ............................................................................................................................. 23 3.7.1 Interface: ISiteResolver ........................................................................................................... 23
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 3 of 23
3.7.2 Site Extension Methods for Site Resolvers ............................................................................. 23
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 4 of 23
Chapter 1 Overview
Sitecore Federated Experience Manager allows activity in non-Sitecore websites and applications to be tracked, and for content managed and personalized by Sitecore to be injected in non-Sitecore websites.
This chapter provides an overview of Sitecore Federated Experience Manager.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 5 of 23
1.1 Capabilities
This section provides an overview of the capabilities of Federated Experience Manager.
1.1.1 Tracking External Sites
Sitecore Analytics allows you to better understand your customers' interests and activities. But if Sitecore is only able to track activity on channels managed by Sitecore, the understanding you are getting is not complete. Therefore, tracking activity on non-Sitecore web sites is an important part of a comprehensive customer engagement strategy.
Sitecore Federated Experience Manager allows you to use the tracking capabilities available on Sitecore web sites to non-Sitecore web sites using a common approach used by analytics vendors.
A small amount of Javascript is added to the non-Sitecore pages that need to be tracked. This Javascript makes a call to Sitecore when a visitor views the non-Sitecore page. Federated Experience Manager creates a Sitecore item that corresponds to the non-Sitecore page. This item is called a "mirror item". The mirror item gives Sitecore a means by which to track activity.
This approach allows Sitecore to use its standard request-handling process for requests to non-Sitecore pages. This means that all of Sitecore's tracking capabilities - profiling, goals, page events, engagement plans, etc. - can be used with non-Sitecore pages.
1.1.2 Personalizing External Sites
Tracking allows Sitecore to better understand your customers' interests and activities. But being able to collect this information is only a small part of the reason you would use Sitecore as a part of your customer engagement strategy. Being able to use this information in order to affect customer engagement is a bigger part of the reason.
Federated Experience Manager allows you to inject personalized content from Sitecore into non-Sitecore web sites. This personalization is able to use the information collect across all channels in order to provide your customers with the most relevant content, even on non-Sitecore web sites.
As explained in the Tracking section, non-Sitecore pages that are tracked have the Federated Experience Manager Javascript added to it. When a visitor views a non-Sitecore page, a request is sent from the visitor's browser to Sitecore. By handling this request Sitecore is able to track the non-Sitecore page view.
In addition to tracking the page view, handling this request also allows Sitecore to generate personalized content. The response that Sitecore returns contents any personalized content that should be injected in the non-Sitecore page. The Javascript that was responsible for making the request to Sitecore is also responsible for injecting the personalized content from Sitecore into the non-Sitecore page.
1.1.3 Tracking External Applications
Tracking is not limited to external sites. Federated Experience Manager allows you to track activity on external applications as well. For example, when a visitor leaves a comment on a non-Sitecore site you might want to record a page event in Sitecore.
This is accomplished by providing a web-based API that allows you to push activity data into Sitecore. After the activity data is passed to Sitecore, Federated Experience Manager allows you to configure how that data should be handled.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 6 of 23
Chapter 2 Conditions & Actions
This chapter describes the conditions and actions that are included with Federated Experience Manager.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 7 of 23
2.1 FXM Analytics
FXM Analytics rules are used to specify the configuration on external applications.
2.1.1 Custom Conditions
Custom conditions must use the type Sitecore.Fxm.Analytics.Rules.EventTrackingContext
as the generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>
2.1.2 Custom Actions
Custom actions must use the type Sitecore.Fxm.Analytics.Rules.EventTrackingContext as
the generic parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 8 of 23
2.2 FXM Content Tracking
FXM Content Tracking rules are used to specify content tracking rules.
2.2.1 Custom Conditions
Custom conditions must use the type
Sitecore.Fxm.ContentTracker.Rules.TrackingRuleContext as the generic parameter when
inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.
2.2.2 Custom Actions
Custom actions must use the type
Sitecore.Fxm.ContentTracker.Rules.TrackingRuleContext as the generic parameter when
inheriting from Sitecore.Rules.Actions.RuleAction<T>.
2.2.3 Apply Tracking Action Base
The most common use for a custom content tracking action is to apply the tracking settings specified on a Sitecore item. The type
Sitecore.Fxm.ContentTracker.Rules.Actions.ApplyTrackingActionBase<T> should be
extended for this type of action.
The following table describes the members of this type:
Method name Description
GetSourceItems(Item) When the Apply method is called, this method is invoked. The collection that is returned is passed to the content tracking pipeline.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 9 of 23
2.3 FXM Page
FXM Page rules are used to support interacting with the result of external page requests. This includes the crawling process and the tracking process.
2.3.1 Custom Conditions
Custom conditions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the
generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.
2.3.2 Custom Actions
Custom actions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the generic
parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 10 of 23
2.4 FXM Template Definition
FXM Template Definition rules are used to determine the template that should be used for mirror items during the crawling process.
2.4.1 Custom Conditions
Custom conditions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as
the generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.
2.4.2 Custom Actions
Custom actions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as the
generic parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 11 of 23
2.5 FXM Tracking
FXM Tracking rules are used to determine which tracking options should be used during the tracking process.
2.5.1 Custom Conditions
Custom conditions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the
generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.
2.5.2 Custom Actions
Custom actions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the generic
parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 12 of 23
2.6 FXM Tracking Configuration
FXM Tracking Configuration rules are used to determine which tracking options should be assigned to mirror items during the crawling process.
2.6.1 Custom Conditions
Custom conditions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the
generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.
2.6.2 Custom Actions
Custom actions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the generic
parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 13 of 23
2.7 FXM Web Crawling
FXM Web Crawling rules are used to control the creating and updating of mirror items during the crawling process.
2.7.1 Custom Conditions
Custom conditions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as
the generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.
2.7.2 Custom Actions
Custom actions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as the
generic parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 14 of 23
2.8 Rule Context Types
This section describes the various rule context types that are used in Federated Experience Manager.
2.8.1 Web Rule Context
The web rule context is used by rules that run during the page crawling process.
The web rule context is implemented by the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext.
The following table describes the members of this type:
Property name Description
HtmlDocument The HtmlAgilityPack.HtmlDocument object
that represents the external page.
Language The Sitecore language that was resolved during the mirror item creation process.
MirrorArgs The args object from the mirror item creation pipeline.
Request The System.Net.HttpWebRequest object that
represents the tracking request.
TemplateId The ID of the template that the mirror item should be based on.
2.8.2 Crawling Context
The crawling context is used by rules that run during the page crawling process.
The crawling context is implemented by the type
Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext. This type inherits from the web rule
context type.
The following table describes the members of this type:
Property name Description
IsPreventedPage The ID of the Sitecore definition item for the external application configuration.
This property is set prior to the configuration rules being run.
UpdatedItems Collection of event processors that are run by the external application tracking process.
These event processors are usually set when actions run, but the can also be set by processors in the external application tracking pipeline.
2.8.3 Event Tracking Context
The event tracking context is used by rules that run during the external tracking process.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 15 of 23
The event tracking context is implemented by the type
Sitecore.Fxm.Analytics.Rules.EventTrackingContext.
The following table describes the members of this type:
Property name Description
ConfigurationId The ID of the Sitecore definition item for the external application configuration.
This property is set prior to the configuration rules being run.
EventProcessors Collection of event processors that are run by the external application tracking process.
These event processors are usually set when actions run, but the can also be set by processors in the external application tracking pipeline.
Uri The URI specified in the tracking request.
This property is set prior to the configuration rules being run. This property is read-only.
2.8.4 Tracking Rule Context
The tracking rule context is used during the content tracking process.
The tracking rule context is implemented by the type
Sitecore.Fxm.ContentTracker.Rules.TrackingRuleContext.
The following table describes the members of this type:
Constructor Description
TrackingRuleContext(Item) Sets the Rule property on the rule context to the specified object. This object is the item which content tracking conditions and actions relate to.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 16 of 23
Chapter 3 Extending Components
This section explains how the different components that make up Federated Experience Manager can be extended.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 17 of 23
3.1 Crawlers
If the Abot crawler that is included with Federated Experience Manager does not meet your needs, you can create your own crawler.
3.1.1 Interface: IWebCrawler
If you wish to create a custom crawler, you should implement the interface
Sitecore.Fxm.Web.Crawler.IWebCrawler.
The following methods must be implemented:
Method name Arguments Description
Crawl Site definition item For each page the crawler handles it runs the page crawling process.
In most cases the return value is not relevant because the crawler will run asynchronously.
StopCrawler (none) In most cases the crawler will run asynchronously. This method allows the crawling process to be interrupted.
WriteLog Message
Log level
This message allows you to log information on the crawler's activity.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 18 of 23
3.2 Event Parsers
This section covers custom event parsers.
3.2.1 Interface: ISingleEventParser
If you wish to create a custom single event parser, you should implement the interface
Sitecore.Fxm.Analytics.Parsers.ISingleEventParser.
The following methods must be implemented:
Method name Arguments Description
Parse Event name
Rule context
Return an IEventProcessor
instance that is able to record the page event specified by the event name parameter.
The rule context object may serve as the source of the properties on the page event.
Note: A custom single event parser will likely depend on the rule context object to provide the data that gets recorded on the page event. As a result, if you implement a custom single event parser it is likely that you will also need to configure custom actions in order to set values on the rule context.
3.2.2 Interface: IMultiEventParser
If you wish to create a custom multi- event parser, you should implement the interface
Sitecore.Fxm.Analytics.Parsers.IMultiEventParser.
The following methods must be implemented:
Method name Arguments Description
Parse Rule context Return a list of
IEventProcessor instances.
Note: Just like with custom single event parsers it is likely you will also need to implement custom actions in order to set the data you want to record in the page event into the rule context object.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 19 of 23
3.3 Event Processors
Event processors are responsible for tracking. The external application tracking process determines which event processors should be used and then it executes those processors.
The most common reasons why you would develop a custom event processor is because you need a custom tracking action or a custom event parser.
3.3.1 Interface: IEventProcessor
If you wish to create a custom single event parser, you should implement the interface
Sitecore.Fxm.Analytics.Processors.IEventProcessor.
The following methods must be implemented:
Method name Description
Process This method performs a task, usually involving tracking. For example, the method may record a goal or it may set a score on the visitor's profile.
If the processor is going to track analytics it should check the value of Sitecore.Analytics.Tracker.IsActive
before recording anything.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 20 of 23
3.4 Language Resolvers
This section covers custom language resolvers.
3.4.1 Interface: ILanguageResolver
If you wish to create a custom site resolver, you should implement the interface Sitecore.Fxm.Web.Languages.ILanguageResolver
The following methods must be implemented:
Method name Arguments Description
EnsurePaths Paths
Language
Removes the language segments from item paths so that the item path does not include the language segments.
ResolveLanguage URI for the inbound tracking request
Returns an object that represents the language that was resolved.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 21 of 23
3.5 Parameter Readers
This section covers custom parameter readers.
3.5.1 Interface: IParametersReader
If the parameter readers that are included with Federated Experience Manager do not meet your needs, you can create your own parameter reader. To create a parameter reader you must implement the
interface Sitecore.Fxm.Analytics.Parameters.IParametersReader.
The following methods must be implemented:
Method name Arguments Description
Read HTTP request Returns an IEnumerable that
contains the parameters as
KeyValuePair objects.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 22 of 23
3.6 Placeholder Selectors
This section covers how to customize the process of determining which placeholder selectors are available for a specific mirror item.
3.6.1 Mirror Provider
The mirror provider is the component that is responsible for determining which placeholder selectors are available for a specific mirror item. The default mirror provider is implemented in the type
Sitecore.Fxm.Web.Mirror.MirrorProvider.
3.6.2 Method: GetPlaceholderSelectors
The "GetPlaceholderSelectors" method on the mirror provider is responsible for returning the placeholder selectors assigned to a specific mirror item.
Name Description
Default implementation Returns the placeholder selectors that are assigned to the mirror item.
Argument: mirrorItem The mirror item whose placeholder selectors are to be retrieved.
Return value List of Sitecore.Data.Items.Item objects
that represent the placeholder selectors.
Sitecore Federated Experience Manager Developer's Guide
Sitecore® is a registered trademark. All other brand and product names are the property of their respective holders. The contents of this document are the property of Sitecore. Copyright © 2001-2015 Sitecore. All rights reserved.
Page 23 of 23
3.7 Site Resolvers
This section covers custom site resolvers.
3.7.1 Interface: ISiteResolver
If you wish to create a custom site resolver, you should implement the interface
Sitecore.Fxm.Web.Sites.ISiteResolver.
The following methods must be implemented:
Method name Arguments Description
ResolveSite Site definition item Returns the Sitecore.Sites.Site
instance that represents the external site.
This method should call the methods defined in section 3.7.2.
3.7.2 Site Extension Methods for Site Resolvers
Federated Experience Manager includes extension methods for the type Sitecore.Sites.Site.
These extension methods are defined in the assembly Sitecore.Fxm.Web. These methods are called
by site resolvers.
Method name Arguments Description
MarkAsFxmWebSite (none) Sets a property on the site that identifies the site as an external site. This property is used to determine whether the crawling process should run.
SetSiteItemId Site definition item ID Sets a property on the site that identifies the site definition item.
Top Related