Salesforce Commerce Cloud: Controllers
The Dynamic Yield–Salesforce Commerce Cloud cartridge provides a quick way to implement Dynamic Yield, as it takes care of the basic implementation of Dynamic Yield on the site (script, page context, e-commerce events, and product feed). Part of the setup requires technical knowledge of Salesforce Commerce Cloud.
The cartridge is self-contained and can be integrated into any project. It can be configured in Business Manager and contains all elements necessary to integrate systems into any e-commerce environment.
If your environment is based on SFRA, see the Salesforce Commerce Cloud: SFRA article.
Prerequisite
This cartridge is designed for Salesforce Commerce Cloud API version 18.10, Compatibility Mode: 18.10. If you're using a different version, manual changes might be required.
Step 1: Create a Dynamic Yield section
Complete this step in Experience OS.
A section in Dynamic Yield Experience OS represents your store's site in our system. Each section has an associated product feed, which is your product catalog. You'll configure the sync of the catalog/feed in the following steps.
To create the section, go to Experience OS and follow the directions in Managing Sections in our Knowledge Base.
Step 2: Install the cartridge in the sandbox
Complete this step in Salesforce Commerce Cloud:
-
Download the cartridge here.
-
Open Salesforce Commerce Cloud Studio.
-
Import the following downloaded cartridges into your IDE workspace:
int_dynamicyield and bc_dynamicyield. -
Link the cartridge to the sandbox as follows:
- Select sandbox connection and select Properties.
- Select Project Reference.
- Check in int_dynamicyield and bc_dynamicyield.
For more details, see the For more details, see the Salesforce Commerce Cloud documentation.
-
Verify that the cartridge has been installed by going to Business Manager › Merchant Tools › Site Preferences › Custom Site Preference and confirming that the Dynamic Yield folder is there.
Step 3: Set up the Business Manager
Complete this step in Salesforce Commerce Cloud:
-
Go to Business Manager › Administration › Sites › Manage Sites.
-
Select your site, and go to the Settings tab.
-
In cartridges, add int_dynamicyield to the end of the line as follows:
-
Go back to Business Manager › Administration › Sites › Manage Sites.
-
Select the site Business Manager, and go to the Settings tab.
-
In cartridges, add the string :bc_dynamicyield.
-
Go to Business Manager › Site Development › Site Import & Export.
-
Upload the file metadata/dynamicyield.zip. This file contains all the necessary settings for the site.
-
Import the file you just uploaded by selecting it and clicking Import. Click Yes to confirm.
-
Verify that the implementation was successful by going to your test StoreFront and checking that the Dynamic Yield icon appears as shown in the following image:
Step 4: Configure the cartridge in Site Preferences
Complete this step in Salesforce Commerce Cloud
- Go to Business Manager: Sites › Your Site › Site Preferences › Custom Site Preferences › Dynamic Yield.
- Verify that Enable Dynamic Yield and Enable Catalog Export are set to Yes.
- Enter your Dynamic Yield Site ID.
- Enter the Product Feed’s S3 Access Key ID and Secret Access Key.
- If your product feed has custom columns beyond the mandatory columns, add them in the Product Attributes field. You can add up to 30. Note that custom columns can't be removed later.
Custom columns can be used for targeting (say, add "color" and target users who purchased blue items), affinity score (include color affinity in the affinity recommendation algorithm), define merchandising rules in your recommendation widgets (never recommend products of a specific brand).
- Enter the Dynamic Yield Endpoint for Product Feed uploading (only host part):
- If you're using our US data center:
com.dynamicyield.feeds - If you are using our EU data center:
dy-datafeeds-eu
Also set Enable Dynamic Yield Europe Account to Yes
- If you're using our US data center:
How can you tell if you use the .com or .eu data center?
If your site ID starts with 8 – use the .com information.
If your site ID starts with 9 – use the .eu information.
- Dynamic Yield uses an extremely fast dedicated CDN. However, if you want to use your own CDN, configure the following settings:
- Enable CDN integration: Yes.
- Custom CDN URL: A link to your CDN in the following format:
<script type="text/javascript" src="//[CUSTOM CDN URL]/api/[SECTION_ID]/api_dynamic.js"></script> <script type="text/javascript" src="//[CUSTOM CDN URL]/api/[SECTION_ID]/api_static.js"></script>
- Enable async integration: Usually set to No. If you configure the scripts to run asynchronously, unexpected behaviors will occur, affecting which variations are shown, loading times, flicker, and so on. Dynamic Yield provides a high server redundancy rate and fast loading times, so you don’t need to resort to asynchronous loading to speed things up. All other operations after loading the scripts are run asynchronously.
Step 5: Sync your product catalog with Dynamic Yield
Complete this step in Experience OS.
A synced product feed enables capabilities like recommendations, segmenting based on product engagement, social proof tactics, and more.
To enable the sync, you must enter the AWS S3 access and secret keys. To get these credentials:
-
In Experience OS, go to Assets › Data Feeds.
-
Do one of the following:
- If you already have a product feed, go to your feed and click Edit.
- If you don't yet have a product feed, click Add New to create one.
-
In the Feed Source, select Sync a file via Amazon S3.
-
Do one of the following:
-
If you're editing an existing product feed, click Generate Credentials.
-
If you're creating a new feed, click Create a bucket.
The Access Key and Secret Key are displayed.
-
Step 6: Configure the product feed sync schedule
Complete this step in Salesforce Commerce Cloud
- Go to Business Manager: Administration › Operations › Job Schedules › Dynamic Yield.
- Go to the Schedule and History tab to define the synchronization schedule.
- Verify that Enabled is checked.
- Configure the Trigger for syncing the product catalog with Dynamic Yield:
- Recurring Intervals (recommended): To automatically sync the feed periodically and keep the product feed updated with your product catalog.
- Once: Sync only once. Note that if your product catalog changes later, it won't update the product feed in Dynamic Yield.
- Use the date picker in the From and To fields to define the first time to run the job, and when to no longer run it. If the To field is blank, the job will continue to run according to the run time schedule (configured in the next step). We recommend choosing today as the start date and keeping the end date empty.
- The Run Time configuration determines your sync interval (minimum: 60 minutes).
- Go to the Step Configurator tab and click Organization.
- Select the needed site for this job and click Assign.
Configure events
The cartridge supports the following events out of the box:
➡ Purchase ➡ Add to Cart ➡ Signup
➡ Login ➡ Remove from Cart ➡ Sync Cart
➡ Sort Items ➡ Filter Items ➡ Change Attribute
➡ Keyword Search ➡ Promo Code Entered
To add additional events:
- Go to int_dynamicyield/cartridge/scripts/helper/dyHelper.js and locate the getDYresponse function. Use the examples of supported events to add custom events.
- Add the events to your JS code wherever you want to trigger them.
- Each event also requires a call from the client JS scripts to the DynamicYield-GetAPIProperties endpoint.
Learn more about Dynamic Yield events.
Step 8: Validate the implementation
Complete this step in Experience OS.
After implementing Dynamic Yield, it's important to validate that your script, page context, events, and data feed are properly set up. For details, see Validating your Web Implementation.
Step 9: Modify the code base
Make code modifications in the following files.
1. cartridge/templates/default/util/modules.isml
Paste this code snippet from line 382 in cartridge/templates/default/util/modules.isml to the parallel file in your code base.
<ismodule template="dynamicyield/callrender"
name="dynamicyield" attribute="page_type" />
2. cartridge/scripts/util/Resource.ds
Paste this code snippet from line 202 in cartridge/scripts/util/Resource.ds to the parallel file in your code base..
DYGetAPIProperties:
URLUtils.url('DynamicYield-GetAPIProperties').toString()
3. cartridge/templates/default/components/footer/footer_UI.js
Paste this code snippet from line 35 in the cartridge/templates/default/components/footer/footer_UI.js file to the parallel file in your code base.
<script src="${URLUtils.staticURL('/js/dynamicyield.js')}"></script> <script>
$( document ).ready(function() {
$('#email-alert-signup button').on('click',function(e){
e.preventDefault(); var DYform = $(this).closest('form'); var email = $('#email-alert-address').val();
dynamicYield.callEvent('Newsletter Subscription', {email: email, DYform: DYform});
});
});
</script>
<isif condition="${!empty(session.custom.DYnewSession) &&
session.custom.DYnewSession=='true'}">
<script>
$( document ).ready(function() {
dynamicYield.callEvent('Sync cart'); });
</script>
</isif>
4. cartridge/js/pages/product/addToCart.js
Copy the following code to the file as shown.
var quantity = $qty.val();
var productId = $form.find('input[name="pid"]').val();
dynamicYield.callEvent('setAddedItem', {productId: productId, quantity: quantity});
dynamicYield.callEvent('Add to Cart', {productId : productId, quantity: quantity});
5. cartridge/templates/default/account/wishlist/pt_wishlist.isml
- Copy the following code to the file as shown.
<isdynamicyield page_type="OTHER"/>
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() { dynamicYield.callEvent('Account');
$('.add-to-cart').click(function(){
var $line = $(this).closest('tr');
$qty = $line.find('input[name="Quantity"]');
if ($qty.length === 0 || isNaN($qty.val()) || parseInt($qty.val(), 10) === 0) { $qty.val('1');
}
var quantity = $qty.val();
var productId = $line.find('.sku .value').text();
dynamicYield.callEvent('setAddedItem', {productId: productId, quantity:
quantity});
});
});
</script>
6. cartridge/templates/default/checkout/cart/pt_cart.isml
- Copy the following code to the file as shown.
<isdynamicyield page_type="CART"/>
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() {
$("[name$='_deleteProduct']").click(function(e) {
e.preventDefault();
var thisName = $(this).attr('name');
$(this).append('<input type="hidden" value="Remove" name="'+thisName+'">');
var DYform = $(this).closest('form');
var line = $(this).closest( "tr" );
var quantity = line.find('.item-quantity input').val();
var productId = line.find('.sku .value').text();
dynamicYield.callEvent('setRemovedItem', {productId:
productId, quantity: quantity, DYform: DYform});
});
$('.add-to-wishlist').click(function(e){
e.preventDefault();
var line = $(this).closest( "tr" );
var DYhref = $(this).attr("href");
var productId = line.find('.sku .value').text();
dynamicYield.callEvent('Add to Wishlist', {productId: productId, DYhref: DYhref});
});
});
</script>
<isscript>
var couponCatch = '';
try {
couponCatch = newCoupon;
} catch(e){
couponCatch = '';
}
</isscript>
<isif condition="${!empty(newCoupon)}">
<script>
$( document ).ready(function() {
dynamicYield.callEvent('Promo Code Entered', {code: '<isprint value="${newCoupon}" encoding="htmlsinglequote"/>'});
});
</script>
</isif>
<isif condition="${!empty(session.custom.DYaddedItem)}">
<script>
$( document ).ready(function() {
dynamicYield.callEvent('Add to Cart');
});
</script></isif>
<isif condition="${!empty(session.custom.DYremovedItem)}">
<script>
$( document ).ready(function() {
dynamicYield.callEvent('Remove from Cart');
});
</script>
</isif>
7. cartridge/templates/default/product/components/variations.isml
Copy the following code to the file as shown.
var swatchtype = $(this).data('swatchtype');
dynamicYield.callEvent('Change Attribute', swatchtype);
8. cartridge/js/pages/product/variant.js
- Copy the following code to the file as shown.
data-swatchtype='{"type": "${attr.displayName}", "value":
"${attrValue.displayValue}"}'
- Copy the following code to the file as shown.
dynamicYield.callEvent('Change Attribute', {
type: $(this).parent().parent().find('span').text().trim(),
value: $(this).find(':selected').text().trim() })
9. cartridge/js/pages/search.js
Copy the following code to the file as shown.
var urlParam = $(this).find('option:selected').val();
urlParam = urlParam.substring(urlParam.indexOf('srule=')+6); urlParam = urlParam.substring(0, urlParam.indexOf('&')); var srules = {
'best-matches': {sortBy: 'Best Matches', sortOrder: 'ASC'},
'price-low-to-high': {sortBy: 'Price', sortOrder: 'ASC'},
'price-high-to-low': {sortBy: 'Price', sortOrder: 'DESC'},
'product-name-ascending': {sortBy: 'Product Name', sortOrder: 'ASC'},
'product-name-descending': {sortBy: 'Product Name', sortOrder: 'DESC'},
'brand': {sortBy: 'Brand', sortOrder: 'ASC'},
'most-popular': {sortBy: 'Most Popular', sortOrder: 'ASC'}, 'top-sellers': {sortBy: 'Top Sellers', sortOrder: 'ASC'}
}
var params = srules[urlParam];
dynamicYield.callEvent('Sort Items', params);
10. cartridge/templates/default/checkout/pt_orderconfirmation.isml
- Copy the following code to the file as shown.
<isdynamicyield page_type="OTHER"/>
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() {
dynamicYield.callEvent('Purchase', {orderId: '<isprint value="${Order.orderNo}" encoding="htmlsinglequote"/>'});
});
</script>
11. cartridge/templates/default/search/pt_productsearchresult.isml
- Copy the following code to the file as shown.
<isif condition="${(pdict.CurrentHttpParameterMap.cgid.submitted &&
pdict.CurrentHttpParameterMap.cgid.value != '')}">
<isdynamicyield page_type="CATEGORY"/>
<iselse>
<isdynamicyield page_type="OTHER"/> </isif>
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() {
$(document).on('click','.refinement:not(.category-refinement) a',function(){
if(!$(this).parent().hasClass('selected')){
var data = $(this).data('filter');
dynamicYield.callEvent('Filter Items', data);
}
});
<isif condition="${!empty(searchPhrase)}">
dynamicYield.callEvent('Keyword Search', {keywords: '<isprint value="${searchPhrase}" encoding="htmlsinglequote"/>'});
</isif>
$(document).on('click','.js-add-to-wishlist',function(e){
e.preventDefault();
var DYhref = $(this).attr("href");
var productId = $(this).data('pid');
dynamicYield.callEvent('Add to Wishlist', {productId: productId, DYhref: DYhref});
});
});
</script>
12. cartridge/templates/default/search/pt_categorylanding.isml
Copy the following code to the file as shown.
<isdynamicyield page_type="CATEGORY"/>
13. cartridge/templates/default/search/pt_productsearchresult_nohits.isml
- Copy the following code to the file as shown.
<isdynamicyield page_type="OTHER"/>
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() {
<isif condition="${!empty(pdict.ProductSearchResult.searchPhrase)}">
dynamicYield.callEvent('Keyword Search', {keywords: '<isprint value="${pdict.ProductSearchResult.searchPhrase}" encoding="htmlsinglequote"/>'});
</isif>
});
</script>
14. cartridge/templates/default/search/components/productsearchrefinebar.isml
Use the example file in the cartridge to update the code in your code base.
- In line 54, replace
<isdynamicyield page_type="OTHER"/>
with
<a data-filter='{"type":
"${RefinementValue.getID()}", "value": "${RefinementValue.getValue()}"}'
href="${pdict.ProductSearchResult.urlRefineCategory('Search-Show',
path.get(0).ID)}">
- In lines 105, 111, and 117, add this code for each
<a>
tag:
data-filter='{"type": "${RefinementValue.getID()}", "value":
"${RefinementValue.getValue()}"}'
For example, in line 105, update this code:
<a id="${swatchID}"
href="${StringHelpers.unsanitizeOR(pdict.ProductSearchResult.urlRelaxAttributeValue('Search-Sh ow',RefinementValue.getID(),RefinementValue.getValue()))}" title="${Resource.msgf('global.refinement.selected.label','locale',null, RefinementDefinition.displayName, RefinementValue.getDisplayValue())}">
to look like this:
<a id="${swatchID}" data-filter='{"type": "${RefinementValue.getID()}", "value":
"${RefinementValue.getValue()}"}'
href="${StringHelpers.unsanitizeOR(pdict.ProductSearchResult.urlRelaxAttributeValue('Search-Sh ow',RefinementValue.getID(),RefinementValue.getValue()))}" title="${Resource.msgf('global.refinement.selected.label','locale',null, RefinementDefinition.displayName, RefinementValue.getDisplayValue())}">
- In lines 173 and 180, add this code snippet to the
<a>
tag:
data-filter='{"type": "${RefinementDefinition.getDisplayName()}",
"value": "${RefinementValue.getDisplayValue()}"}' code code
For example:
<a class="refinement-link"
title="${Resource.msg('global.pricerefinement.label.prefix','locale',null)}
${RefinementValue.getDisplayValue()}"
data-filter='{"type":"${RefinementDefinition.getDisplayName()}",
"value": "${RefinementValue.getDisplayValue()}"}'
href="${StringHelpers.unsanitizeOR(pdict.ProductSearchResult.urlRefinePrice('Search-Show',Refi nementValue.getValueFrom(),RefinementValue.getValueTo()))}">
15. cartridge/templates/default/product/productcontent.isml
Add the highlighted areas to the file:
<a class="button simple js-add-to-wishlist
" data-action="wishlist" data-pid="${pdict.Product.ID}"
href="${URLUtils.https('Wishlist-Add', 'pid', pdict.Product.ID, 'source', 'productdetail')}"
title="${Resource.msg('global.addtowishlist.label','locale',null)}">${Resource.msg('global.addtowishlist','loc ale',null)}</a>cartridge/templates/default/account/wishlist/pt_wishlist.isml
16. cartridge/templates/default/product/pt_productdetails.isml
- Copy the following code to the file as shown.
<isinclude template="util/modules" />
<isdynamicyield page_type="PRODUCT"/>
- Copy the following code to the pageContext call.
productID: (pdict.Product.ID || ''),
For example:
var pageContext = {
title: (pdict.Product.name || 'Product Detail'),
productID: (pdict.Product.ID || ''), type: 'product',
ns:'product'
};
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() {
$(document).on('click','.js-add-to-wishlist, a[data-action=wishlist]',function(e){ e.preventDefault();
var DYhref = $(this).attr("href");
var productId = $(this).data('pid') || window.pageContext.productID;
dynamicYield.callEvent('Add to Wishlist', {productId: productId, DYhref: DYhref});
});
});
</script>
17. cartridge/templates/default/account/pt_account.isml
- Copy the following code to the file as shown.
<isdynamicyield page_type="OTHER"/>
- Copy the following code to the file as shown.
<script>
$( document ).ready(function() {
dynamicYield.callEvent('Account');
});
</script>
19. cartridge/templates/default/checkout/cart/cart.isml
- Copy the following code to the file as shown.
<isset name="appliedCoupons"
value="${new dw.util.ArrayList()}" scope="page" />
- Copy the following code to the file as shown.
<isset name="isAppliedCoupons"
value="${appliedCoupons.add(FormCoupon.object.couponCode)}"
scope="page" />
- Copy the following code to the file as shown
<isscript> var DYcoupons = []; var newCoupon = '';
var appliedCoupons = appliedCoupons.toArray(); if(!empty(appliedCoupons)){
// When at least one coupon was used
if(!empty(session.custom.DYcoupons)){
// When at least one coupon was saved to our session
DYcoupons = session.custom.DYcoupons.split('|');
if( DYcoupons.length < appliedCoupons.length ){ // new coupon was used and need to find it for (var i in DYcoupons) { if(DYcoupons[i] != appliedCoupons[i]){ newCoupon = appliedCoupons[i]; break;
}
}
if(newCoupon==''){
i++;
newCoupon = appliedCoupons[i];
}
} // else coupon was removed or not added
} else {
// we didn't call our event yet
newCoupon = appliedCoupons[0];
}
}
session.custom.DYcoupons = appliedCoupons.join("|"); </isscript>
20. cartridge/templates/default/product/components/options.isml
Copy the following code to the file as shown.
<script> setTimeout(function() {
$(document).ready(function() {
$('select').each(function(i,e) {
$(e).on('change', function(el) {
var $el = $(el.currentTarget).find(':selected'); dynamicYield.callEvent('Change Attribute', {type: $(el.currentTarget).parent().parent().find('span').text(), value: $el.text()})
})
})
})
},100)
</script>
21. cartridge/js/pages/checkout/billing.js
Copy the following code to the file as shown.
if (data.success) {
dynamicYield.callEvent('Promo Code Entered', {code: code, ajax: true});
if(data.baskettotal === 0){
window.location.assign(Urls.billing);
}}
21. cartridge/js/pages/checkout/billing.js
Copy the following code to the file as shown.
if (data.success) {
dynamicYield.callEvent('Promo Code Entered', {code: code, ajax: true});
if(data.baskettotal === 0){
window.location.assign(Urls.billing);
}}
22. cartridge/templates/default/content/home/pt_storefront.isml
Copy the following code to the file as shown.
<isdynamicyield page_type="HOMEPAGE"/>
23. cartridge/templates/default/
Copy the following code to these files:
- cartridge/templates/default/content/pt_customerservice.isml line 18
- cartridge/templates/default/content/content/pt_content.isml line 11
- cartridge/templates/default/account/giftregistry/pt_giftregistry.isml line 24
- cartridge/templates/default/account/orderhistory/orders.isml line 4
<isdynamicyield page_type="OTHER"/>
Updated 9 months ago