How to Perform Advertising and Marketing Operations in Commerce Server
Using the Microsoft Multi-Channel Commerce Foundation APIs, this how-to describes how you can retrieve multiple advertisements, including retrieving multiple advertisements targeted for a specific channel (using customization noted in the Comments section of this document) and retrieving an advertisement targeted against a specific product (using customization noted in the Comments section of this document). For each sample, you may need to refresh the page several times to observe the behavior that configuration has on the ads to be displayed. This how-to also shows how to create a record to track marketing events, such as users clicking on advertisements.
Note This sample code is provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices. Microsoft assumes no liability for incidental or consequential damages should the sample code be used for purposes other than as intended.
Prerequisites
- You can access the sample code by extracting the .zip archive in the samples folder you selected when you installed the Commerce Server 2009 R2 SDK Samples. In order to use these samples it is assumed that you have extracted them
Unpackage and Configure the PUP
You must first unpackage and configure the included Commerce Server site via the PUP file "SolutionStorefrontWithSampleData.pup".
The samples depend upon the data within this package.
To create the Commerce Server site
In Windows Explorer, navigate to the <dir>\Pup Packages.
Double-click the SolutionStorefrontWithSampleData.pup file.
In the Unpack screen, select Quick Unpack, and then click Next.
In the Quick Unpack screen, ensure that the SQL Server computer name is correct, enter the SQL Server login name and password or select Windows Authentication as the authentication method, and then click Next.
In the Profiling System screen, accept the defaults, and then click Next.
In the second Profiling System screen, accept the defaults, and then click OK.
In the Commerce Server Site Packager dialog box, click OK.
In the Unpacking is complete! screen, click Finish.
The Commerce Server site is unpacked to the Solution Storefront in IIS.
Building the Solution
You will have to build the MarketingAPIUsage.sln before proceeding.
To build the solution within Visual Studio
In Windows Explorer, go to <dir>\Extensibility Kits\Samples\.
Unzip the FoundationSamples.zip to a new directory.
Browse to the FoundationSamples folder.
Double-click the Marketing folder.
Double-click the MarketingAPIUsage.sln file. This opens the solution in Visual Studio.
Under Solution Explorer, right-click Solution <solution name>, and from the context menu select Build Solution.
Creating a Web Application
Use the following steps to add the sample application to your Commerce Server site in Internet Information Services (IIS). When you do so, you will choose an IIS application pool to assign to the Web application. To make sure that the application works correctly, the application pool you select must comply with the following:
- The application pool must have all the necessary security privileges to access your Commerce Server site and its associated databases.
To add the application to the Commerce Server site in IIS 7.0
In Internet Information Services (IIS) Manager, in the navigation tree, click Sites, right-click Default Web Site, and then click Add Application.
In the Alias box, type a name for your sample.
Click the Select button next to the Application pool box, select the application pool to use, and then click OK.
Note
The application pool must have all the necessary security privileges to access your Commerce Server site and its associated databases.
In the PhysicalPath box, type the full path of the application. This is the path to which you browsed to the FoundationSamples\Marketing folder.
For example, when you extract the FoundationSamples.zip to the same folder, the application path is as follows: %commerce_server_root%Extensibility Kits\Samples\FoundationSamples\Marketing.
Click OK.
The advertisement image paths are configured within the advertisements. Depending upon where you created your application, you may need to adjust them. To do this:
Open Commerce Server 2009 Marketing Manager.
Select All Ads.
For each ad
i. Edit the ad
ii. Disapprove the ad
iii. Select the Display tab
iv. Prepend the Image URL field to include the relative path for your web site. For example, /MarketingSample.
v. Save the ad.
vi. Approve the ad.
Under Tasks click Refresh Site Cache.
In Internet Explorer, go to the following URL to access the Web application:
https://localhost/<your_sample_vdir>/Default.aspx
where <your_sample_vdir> is the value used in step 4.
Retrieving Advertisements
You can augment this sample code to target Advertisements for a specific channel or product.
To Retrieve Advertisements for a specific channel
Open Commerce Server 2009 Marketing Manager.
Select All Ads.
Edit SampleAd3 (Full Banner)
Disapprove the Ad.
Select the Targeting tab.
In the Target Expressions section, click the Add... button.
Select the Default Channel expression and click OK.
Change the Action value for the expression from Target to Require
Save and Approve the ad.
Repeat the operations in step 3 for SampleAd3 (Square button) and SampleAd3 (Vertical Banner).
Under Tasks click Refresh Site Cache.
This has the effect of targeting the aforementioned Ads to the "Default" Channel. Inspecting the CommerceFoundationServiceAgent.cs class, the channel name is configured as SampleChannel. The aforementioned ads will no longer be displayed within the application since we configured them to target the Default channel. You can confirm this by noticing that ads with a green background are no longer displayed within the application.
To Retrieve Advertisements for a specific product
Open Commerce Server 2009 Marketing Manager.
Under the Tasks panel, click Set Targeting Profiles.
If Product is not in the Targeted column, select it from the Profiles list and click Add.
Click OK.
In the Views pane, select Campaigns, and then select All Ads under the Tree View.
Edit SampleAd1 (Full Banner).
Disapprove the ad.
Select the Targeting tab.
In the Target Expressions section, click Create New Expression.
i. Set the expression name to ProductAd.
ii. In the Expression Clauses grid, add the following clause:
Product.ProductId Is equal to AW200-12
iii. Click OK.
Change the Action value for the expression from Target to Require.
Save and Approve the ad.
Under Tasks click Refresh Site Cache.
This has the effect of making SampleAd1 (Full Banner) only display when the product Id is equal to AW200-12. SampleAd1 (Full Banner) will now be displayed on the AllAdsAndProductAds.aspx page, but not on the AdsBrowse.aspx page.
Note
The call to MarketingManager.GetContent() in the AllAdsAndProductAds.aspx.cs code is including the product Id as part of its targeting whereas it is not specified in the AdsBrowse.aspx.cs call to MarketingManager.GetContent().
Example
The following code snippet illustrates how to build a query to retrieve advertisements for a specific channel. It assumes usage of wrappers that are included in the sample.
// Build Content selector query
CommerceQuery<ContentSelector> query = new CommerceQuery<ContentSelector>();
query = Manage(query, contentSelectorType);
if (!string.IsNullOrEmpty(pageGroup))
{
query.SearchCriteria.Model.PageGroup = pageGroup;
}
if (!string.IsNullOrEmpty(contentSize))
{
query.SearchCriteria.Model.Size = contentSize;
}
// Get user's campaign history from site context
if (CommerceFoundationServiceAgent.UserCampaignHistory != null)
{
query.SearchCriteria.Model.CampaignHistory = CommerceFoundationServiceAgent.UserCampaignHistory.Value.Split(",".ToCharArray());
}
// Setting user Id in search criteria
query.SearchCriteria.Model.UserId = CommerceFoundationServiceAgent.UserId;
// Get default catalog name
query.SearchCriteria.Model.CatalogName = CommerceFoundationServiceAgent.CatalogName;
// Setting product Id to search criteria
if (!string.IsNullOrEmpty(productId))
{
query.SearchCriteria.Model.ProductId = productId;
}
// Build the run time properties
TargetingContext targetingContext = new TargetingContext();
targetingContext.Properties["Channel"] = CommerceFoundationServiceAgent.Channel;
query.SearchCriteria.Model.TargetingContext = new CommerceRelationship(targetingContext.ToCommerceEntity());
CommerceResponse response = CommerceFoundationServiceAgent.Execute(query);
if (response.OperationResponses.Count > 0)
{
foreach (CommerceQueryOperationResponse queryResponse in response.OperationResponses)
{
if (queryResponse.Count > 0)
{
foreach (ContentSelector contentSelector in queryResponse.CommerceEntities)
{
if (contentSelector.Advertisements != null)
{
foreach (CommerceRelationship ad in contentSelector.Advertisements)
{
Advertisement advertisement = (Advertisement)ad.Target as Advertisement;
requiredContent.Add(new ItemData(advertisement.Id, advertisement.Content));
}
}
}
}
}
}
return requiredContent;
}
The following code snippet illustrates how to create a record to track marketing events, such as users clicking on an advertisement. It assumes usage of wrappers that are included in the sample.
CommerceCreate<EventRecord> eventRecord = new CommerceCreate<EventRecord>();
eventRecord.Model.AdvertisementId = contentId;
eventRecord.Model.EventName = "Click";
eventRecord.Model.PageGroupId = pageGroupId;
eventRecord.Model.ContextName = "Advertisement";
CommerceFoundationServiceAgent.Execute(eventRecord);