# Tuesday, 18 October 2011

Foundation-logouCommerce comes with a bunch of built-in targets that you can use to set up new campaign items, but you can extend Marketing Foundation with your own targets as well.

To build a new target you have to deal with three concerns:

  • Business logic, this is the target itself
  • User interface, the UI a customer will use to configure your target
  • Data access, creating new instances of your target and loading existing ones

“Buy More Than”-target

In this article you will learn how to extend Marketing Foundation with a “Buy more than”-target, which is what uCommerce calls an Act target. The “Buy more than”-target will be an order line level target, which will be combined with a “Buy product”-target to create a discount triggered.

It can be used stand-alone as well in which case the customer just needs to “Buy more than” of whatever product she decides. Not the most common discount type, but it does show the power of being able to combine targets.


Advertise and Act Targets

uCommerce supports two kinds of targets: The advertise target and the act target. Display targets are used in the process of targeting campaign items for specific customers, i.e. these are the ones you set up under the “Advertise” section of a campaign item.

Act targets are evaluated against a cart to determine whether the customer actually “acted” the way we wanted them to and thus trigger an award.

A target might be either an advertise target, an act target, or both, e.g. a product target is actually both an advertise target and an act target as it works for both scenarios.

As mentioned advertise targets are used to determine which campaign items a customer should see using the XSLT extension:

<xsl:variable name="targetedCampaignItems" select="CommerceLibrary:GetTargetedCampaignItems()"/>

Or via .NET

var targetingService = ObjectFactory.Instance.Resolve<ITargetingService>();
IList<CampaignItem> targetedCampaignItems = targetingService.GetTargetedCampaignItems();

Act targets are executed by the basket pipeline using the pipeline task Basket.ApplyAwards.

Our “Buy more than”-target will be an act target targeting individual order lines. Before we get to that though let’s take a look at what’s required to create an advertise target or IDisplayTarget as they’re called internally in uCommerce.

Implementing IDisplayTarget


To implement a display target you’ll implement the interface called IDisplayTarget, which has a single method called IsSatisfiedBy. This is the method invoked by uCommerce to determine whether the target is satisfied by the current targeting context.

Basically you’ll evaluated the targeting context and see if it fits with what you want your target to do, e.g. is the customer viewing a particular product, is the customer logged, etc..

Pretty simple.

A Word On The TargetingContext


The targeting context is gathered by uCommerce during runtime and tells you all manner of interesting information about what the customer is currently viewing, e.g. what’s the current page, store, catalog, category, list of products being viewed, etc.. You can add your own information to the targeting context if you require additional information. We’ll cover that in another article.

Implementing An Act Target: IPurchaseOrderTarget, IOrderLineTarget


Act targets are evaluated against the customer’s cart to verify that the customer actually bought or did what we wanted her to do. You can opt into two interfaces depending on whether you’re targeting the entire order or individual order lines: IPurchaseOrderTarget and IOrderLineTarget.

For our “Buy more than” target we’ll implement the IOrderLineTarget because that’s where we’ll find the quantity of a particular item. Our new “Buy more than”-target would probably be combined with a “Buy this product”-target in most cases, which would require a customer to buy a certain amount of the product.


As you can see the logic is pretty simple. We’re receiving an order line from Marketing Foundation and our job is to figure our whether the target is satisfied by this particular order line. In our case the customer just needs to buy more than the configured quantity on the our target.

This leads us to the next question: How do we actually configure a target? Enter the ITargetUi and IConfigurable…

Implementing Configuration UI for the Target

The configuration UI for our new target is responsible for creating a new instance of our particular target and saving it the data store of your choice. Also it serves to reconfigure existing targets of the type that we’re working with; in this instance QuantityTarget.

To add a config UI for our new target we need to create a new user control in .NET. Let’s put it in /umbraco/ucommerce/marketing/targets, which is where the standard target UIs are located. Also remember to put the generated DLL in the /bin folder.

Our user control needs to plugin into the UI framework defined by uCommerce. All that’s required to do so is to inherit ViewEnabledControl<IEditCampaignItemView> and implement IConfigurable.


Inheriting ViewEnabledControl<IEditCampaignItemView> gives us access to the context in the UI, i.e. the campaign item currently being configured.

IConfigurable is the interface which lets uCommerce create your target and subsequently reconfigure it when a user wants to edit it.


For our target we need a specialized version of IConfigurable called ITargetUi. This is due to the fact that the target might be used as both an advertise target, an act target, or both.

uCommerce will tell you whether it’s one context or the other by assigning the EnabledForDisplay and EnabledForApply values on your UI.


So our user control ends up looking like this. Please note that the New() method acts not only as a factory method for our target, but has the responsibility for storing that instance in the data store also. If this doesn’t happen the instance is lost and won’t be displayed as part of the campaign item.


Before we can actually use the control we need to register it with uCommerce.

Register Target Configuration UI

To add the target UI to uCommerce we’ll add it to the table called uCommerce_EntityUi. This table holds the mapping between the type, which is to be configured, i.e. our QuantityTarget, and our UI to do the configuration, i.e. our QuantityUi.ascx user control.


Because uCommerce is multilingual we’ll want to add a description of the new UI in the table uCommerce_EntityUiDescription otherwise the target UI will show up blank in the drop down lists.


When the “Add” button is clicked our new target UI is added to the campaign item and the New() method is called on our user control thus creating a new instance of the target we’re configuring.



With that in place our new UI is now available when setting up new campaign items and we can create new quantity targets, so we’re ready to move on to dealing with existing targets.

Feeding Marketing Foundation with Targets using TargetAggregator

With the previous steps complete we need to deal with existing targets so Marketing Foundation can find them and evaluate them for customers entering the site: Enter the TargetAggregator.

TargetAggregator is responsible for finding targets for any given campaign item configured in Marketing Foundation.

var targetAggregator = ObjectFactory.Instance.Resolve<ITargetAggregator>();
IList<ITarget> targets = targetAggregator.GetTargets(campaignItem);

TargetAggregator relies on individual TargetResolvers to find targets for a campaign item, e.g. uCommerce has a single target resolver called DefaultTargetResolver, which handles the built-in targets.

We’ll build a custom target resolver by implemeting the ITargetResolver. It will handle our Quantity target and any other future targets.


Thus our QuantityTargetResolver ends up looking like this:


Register Custom Target Resolver with TargetAggregator

At this point uCommerce doesn’t know about our custom target resolver yet so we’ll have to tell it about it. This is done using the Marketing configuration file found in /ucommerce/configuration/Marketing.config.

We’ll have to register a new component and add it to the target aggregator registration.

First the new component


And finally grab the id from the component and add it to the target aggregator registration in the same file.


That’s it. Our new target is good to go and will act exactly as the built-in targets, which ship with uCommerce.

In Summary


This article showed you how to add custom targeting logic to uCommerce, the user interface to configure it, and how to handle data access for it as well. When you think about it each target is a mini-application hosted inside uCommerce dealing with all the usual concerns of a full-blown  app.

Some of the concerns like the resolver need only be implemented once while others like the UI and the target itself are highly specific to the task they’re trying to accomplish and require a new implementation for each new type you need.

Marketing and particularly discounting are areas, which often come with very specific business rules highly different dependent on the individual business. uCommerce ships with a bunch of useful targets, but having the ability to add your own ensures that you can accommodate any targeting scenario.

posted on Tuesday, 18 October 2011 17:13:10 (Romance Daylight Time, UTC+02:00)  #    Comments [0] Trackback

Foundation-logoMarketing Foundation introduced with uCommerce 2.0 adds rich marketing capabilities, which can be used to stimulate customers to buy. It’s built based on three simple principles: Advertise, Act, and Award.


One of the common issues with discounts is that customers are never told about them thus a discount does not work its full effect. Basically the customer is only made aware of the discount once they actually trigger it, which is akin to throwing marketing dollars out the window as the customer was likely to buy anyway.

That’s why we built each campaign item in uCommerce to include the “Advertise” component so marketers actively have to decide whether to advertise or not; at the end of the day why wouldn’t you?

When doing advertisements in uCommerce you will select a number of targets, which are to be satisfied in order for the campaign item to be displayed. You can think of them in terms of, “Customer is viewing this category”, “Customer is viewing this page”, “Customer is in this particular store or catalog”.

If multiple targets are configured in the “Advertise” section the campaign item will be displayed if any of the targets are satisfied.

Once a campaign item is targeted for the current customer its contents can be displayed, which includes rich text, video, HTML, and even the actual targets and awards inside the campaign item. What this boils down to is that you can display banners, which feature video, sound, or HTML content and you can take this a step further by actually telling the customer what she needs to do in order to receive a particular discount.


Say you have a campaign item set up called “Free shipping for orders over 400€”. The intent is clear enough, but what if you could actually tell the customer how close she is to get that discount? It just so happens that you can.

Using the information produced by Marketing Foundation you can tell the customer exactly what she must do to trigger the discount.

Say she’s got items in the cart with a total value of 350€. You’d pop up a message telling her that by buying for 50€ more she’d get free shipping; oh and by the way here are some products which 50€ or more making it easy for the customer to take the action we want her to.



The act section of a campaign item is the thing we want the customer to do to trigger a discount. When you think about it a discount is actually composed of two things: The thing we want the customer to do; the act part, and the thing the customer gets; the award part.

Think of “Act” as “The customer must buy this particular product”, “The customer must buy for more than x amount”, “The customer must buy something from this particular store, catalog, or category”, etc.

Targets can be combined to form even more powerful campaign items such as a product bundle or kit depending on which side of the pond you’re on.

If multiple targets are set up in the “Act” section of the campaign item they must all be satisfied in order to trigger the discount. Say you want to the customer to buy two products to get a discount. You’ll set up two targets: One for each of the products in involved. uCommerce will look for these products in the cart of they are both found will trigger the discount.


AwardThe final piece of the puzzle is the “Award”, i.e. the thing the customer gets. The award is completely separate from the rest of the campaign item and thus can be reused for many different types of discounts, e.g. “Buy for more than 400€ and get free shipping ” could also be “Enter this promo code and get free shipping”. The only difference is that the “Buy for more than 400€” act section is substituted with “Enter this promo code”. The award remains the same.

Types of awards include “Get amount of unit price”, “Get amount off order total”, “Get amount off order lines total”, “Get percentage off shipping”. Awards can be combined like targets and effectively gives you a discount for each of the awards configured.

It’s important to distinguish between order discounts and order line discounts. The difference being that order level discounts are typically applied only once per order, e.g. “Get amount off order total” will only add a single discount to the order as you’d expect.

Order line discounts on the other hand can involve multiple order lines as in the case of the bundle or kit. Here two or more order lines are involved in the discount thus each of lines will have the order line discount applied, e.g. “Get 10% off unit price” will produce two discounts; one for each order line satisfied by the Act section.

Campaign Items


The campaign item ties together our “Advertise”, “Act”, and “Award” sections and is the unit, which can be thought of as a “Discount”.  However, the campaign item does more than just set up a discount, it serves as the content for the advertisement as well.

A campaign item is assigned a “definition” when it’s created. The definition determines the content that the marketer can add to the advertisement. So this is basically where you’d add all the rich content we discussed in the beginning of the article.


You can read more about definitions in Catalog Foundation Explained: Product Definitions. The basic concept of the definition is the same for campaign items as for products although obviously a campaign item definition does not deal with variants.

Because the campaign items are configured using definitions you can add your own properties and multilingual properties effectively giving you multilingual marketing campaigns right there. No need to configure the same campaign item twice if you want to target different languages, just add the relevant multilingual properties and you’re done!

Multiple Discounts Per Order, Or No


In some cases you don’t want the customer to receive multiple discounts. That’s where the configuration of the campaign item comes in. Of course you can disable individual campaign items that you don’t customer to receive at all by removing the checkmark in the “Enabled” checkbox.

More interestingly you can configure a campaign item to not allow additional discounts if the “Act” section of current campaign item is satisfied. Combine this with the priority of individual campaign items and you can effectively control which discounts the customer is awarded based on your business rules.

You can prioritize campaign items by right-clicking the campaign and choosing “Prioritize campaign items” in the tree menu.



Finally we come to the top-most level of Marketing Foundation: The campaigns. A marketing campaign is a collection of campaign items grouped together under a name so each campaign will effectively hold all the planned marketing activities for a given period of time.

A marketing campaign is assigned an interval for which it is active. uCommerce will automatically activate campaign items within in the campaign once the activation period is reached and disabled them again once the activation period is done.

In Summary

uCommerce Marketing Foundation is a highly flexible way to set up marketing messages and discounts in your online store. Combined targets and awards make for interesting possibilities when it comes to different discount types and best of all you can let your customers know exactly what they need to do to get a discount, which is the way it should be.

More importantly Marketing Foundation is built-in from the ground up using our Framework First approach, which means that new targets and awards can easily be added. You can even go so far as to change the inner workings on Marketing Foundation. What this means for your online store is that marketing can be tailored to meet your needs exactly.

posted on Tuesday, 18 October 2011 13:34:57 (Romance Daylight Time, UTC+02:00)  #    Comments [0] Trackback