Sitecore Federated Experience Manager Developer's Guide€¦ · Sitecore Federated Experience Manager Developer's Guide Sitecore® is a registered trademark. All other brand and product

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


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



Page 3 of 23

3.7.2 Site Extension Methods for Site Resolvers ............................................................................. 23



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.



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.



Page 6 of 23

Chapter 2 Conditions & Actions

This chapter describes the conditions and actions that are included with Federated Experience Manager.



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



Page 8 of 23

2.2 FXM Content Tracking

FXM Content Tracking rules are used to specify content tracking rules.


Custom conditions must use the type

Sitecore.Fxm.ContentTracker.Rules.TrackingRuleContext as the generic parameter when

inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.


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.



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.


Custom conditions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the

generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.


Custom actions must use the type Sitecore.Fxm.Web.Rules.FxmWebRuleContext as the generic

parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.



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.


Custom conditions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as

the generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.


Custom actions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as the

generic parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.



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.









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.









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.


Custom conditions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as

the generic parameter when inheriting from Sitecore.Rules.Conditions.RuleCondition<T>.


Custom actions must use the type Sitecore.Fxm.Web.Rules.Crawling.CrawlingContext as the

generic parameter when inheriting from Sitecore.Rules.Actions.RuleAction<T>.



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.


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.



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.



Page 15 of 23

The event tracking context is implemented by the type

Sitecore.Fxm.Analytics.Rules.EventTrackingContext.



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.


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.



Page 16 of 23

Chapter 3 Extending Components

This section explains how the different components that make up Federated Experience Manager can be extended.



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.



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.



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.



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.



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.


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.



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



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.



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.



Read HTTP request Returns an IEnumerable that

contains the parameters as

KeyValuePair objects.



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.



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.



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.


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.

Documents

Sitecore Federated Experience Manager Developer's Guide€¦ · Sitecore Federated Experience Manager Developer's Guide Sitecore® is a registered trademark. All other brand and product