On-line marketing macros

You can use macro expressions to dynamically load values related to on‑line marketing applications. Properly using these expressions allows you to set up flexible content and behavior of your websites. With on‑line marketing, macros are required when building conditions for:

You can also use on-line marketing macros in all other parts of Xperience where macros are supported.

Note

All expressions described below are context macros, which means they must be enclosed in {% %} parentheses when entered into text or other general fields. You do not need to use macro parentheses inside macro‑specific fields, such as condition editors.

Live site limitations

The macro expressions described on this page can be used only for Xperience features managed from the administration interface (e.g. managing contact groups or defining automation triggers). Using the on-line marketing macros to render content on the pages of MVC live sites is not supported.

Getting Contact and Scoring data

The fundamental part of most on‑line marketing macros is the loading of a specific contact or its data. Use the following expressions for this purpose:

  • ContactManagementContext.CurrentContact – returns a ContactInfo object representing the current contact, i.e. the visitor who is viewing the website when the macro is resolved.
  • ContactManagementContext.CurrentContactID – returns the ID of the current contact.
  • Contact – you may use this expression when writing conditions for condition-based contact groups or in marketing automation. The Contact macro allows you to work with a general ContactInfo object. For example: Contact.ContactGender == 1

ContactInfo objects serve as a way to access the values set for the given contact (e.g. ContactManagementContext.CurrentContact.ContactLastName). In addition to standard contact fields, you can also use the following advanced properties to get data related to the contact:

ContactInfo property

Description

Accounts

InfoObjectCollection containing all accounts (AccountInfo objects) to which the given contact is assigned.

ContactGroups

InfoObjectCollection containing all contact groups (ContactGroupInfo objects) that contain the given contact.

LastActivity

ActivityInfo object representing the most recently logged activity for the given contact.

Orders

InfoObjectCollection containing all e‑commerce orders (OrderInfo objects) made by the contact on the current site.

Processes

InfoObjectCollection containing all marketing automation processes in which the contact is running.

PurchasedProducts

InfoObjectCollection containing all products (SKUInfo objects) purchased by the contact across all sites in the system.

Wishlist

InfoObjectCollection containing all products (SKUInfo objects) added to the wishlist of the given contact (across all sites in the system).

Working with InfoObjectCollections

There are many ways how you can process InfoObjectCollection objects. For example:




ContactManagementContext.CurrentContact.Accounts.Exists(AccountName == "CompanyAccount")


Checks whether the current contact belongs to an account named CompanyAccount and returns the result as a boolean value.




ContactManagementContext.CurrentContact.Orders.Exists(OrderTotalPrice > 500)


Checks if the current contact has made an order with a total value greater than 500 of the given currency.

On-line marketing macro methods

You can call the following methods inside macro expressions to retrieve on‑line marketing data:

Method

Description / Parameters / Examples

AgreedWithConsent

Returns a bool representing if the contact has given a consent specified in the parameter.

  • ContactInfo contact – contains ContactInfo object of the contact that is to be evaluated.
  • String consentName – specifies the code name of the consent declaration.



ContactManagementContext.CurrentContact.AgreedWithConsent("TrackingConsent")


FilledFormFieldWithValue

Returns a bool representing if the contact has filled in a specific field in a specific form with a given text value.

  • ContactInfo contact – contains ContactInfo object of the contact that is to be evaluated.
  • String formNameField – specifies the name of the form combined with the specific field. Use the “<site name>;<form name>;<form field>” format. For example, “SiteCodeName;ContactUs;FirstName”.
  • String expectedValue – specifies the value the field should contain.



ContactManagementContext.CurrentContact.FilledFormFieldWithValue("SiteCodeName;ContactUs;City", "Chicago")


UnsubscribedFromAllEmails

Returns a bool representing if the contact has unsubscribed from all marketing emails.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.



ContactManagementContext.CurrentContact.UnsubscribedFromAllEmails()


IsInPersona

Returns a bool representing if the contact is assigned to the specified persona.

  • ContactInfo contact – contains the ContactInfo object of the contact that is to be evaluated.
  • Object persona – must contain the appropriate PersonaInfo object of the contact that is to be evaluated.



IsInPersona(ContactManagementContext.CurrentContact, persona)


GetPersona

Returns the persona the contact is currently assigned to. Returns null if the contact is not assigned to a persona.

Note: Always use this method over the ContactPersona property, as this method can correctly take into account the persona selected in the preview mode.

  • ContactInfo contact – contains the ContactInfo object of the contact that is to be evaluated.



ContactManagementContext.CurrentContact.GetPersona()


or




GetPersona(ContactManagementContext.CurrentContact)


LastActivityOfType

Returns an ActivityInfo object representing the activity most recently logged for the specified contact.

  • Object contact – must contain the appropriate ContactInfo object of the contact whose activity should be loaded.
  • String activityType  – optional parameter that may be used to get the last activity of a specific type. The value must be entered as a string matching the code name of the appropriate activity type.



 ContactManagementContext.CurrentContact.LastActivityOfType("purchasedproduct")


or




LastActivityOfType(ContactManagementContext.CurrentContact, "purchasedproduct")


FirstActivityOfType

Returns an ActivityInfo object representing the first activity logged for the specified contact.

  • Object contact – must contain the appropriate ContactInfo object of the contact whose activity should be loaded.
  • String activityType  – optional parameter that may be used to get the first activity of a specific type. The value must be entered as a string matching the code name of the appropriate activity type.



ContactManagementContext.CurrentContact.FirstActivityOfType("productaddedtowishlist")


IsInContactGroup

Returns a bool representing if the contact is a member of the specified contact group.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • String groupNames – must contain the code name of the given contact group.



ContactManagementContext.CurrentContact.IsInContactGroup("MaleCustomers")


GetScore

Returns the total number of score points that the given contact has in the specified score (as an integer).

  • Object contact – specifies the ContactInfo object representing the contact whose score points should be loaded.
  • String scoreName – must contain the code name of the given score.



ContactManagementContext.CurrentContact.GetScore("InterestedInSmartphones")


GetEmailDomain

Reads an email address and returns only its domain part (all characters after the “@” sign).

Note: The GetEmailDomain method is not available when resolving macros in an external application using the Kentico.Xperience.Libraries NuGet package.

  • String email – specifies the email address from which the domain is taken.



ContactManagementContext.CurrentContact.ContactEmail.GetEmailDomain()


CameToLandingUrl

Returns a bool representing if the contact has come to the landing page with the specified URL.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • String URL – defines the part of URL specifying the landing page.



ContactManagementContext.CurrentContact.CameToLandingUrl("smartphones")


VisitedURL

Returns a bool representing if the contact has visited a page with the specified URL in the last X days.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • String URL – specifies the URL of the page that has been visited.
  • Int lastXDays – optional parameter specifying how many days ago the page was visited. If you enter the zero value, no constraint is applied.



ContactManagementContext.CurrentContact.VisitedUrl("smartphones", 5)


VisitedSite

Returns a bool representing if the contact has visited the specified site.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • String siteName – specifies the code name of the site that has been visited.
  • Int lastXDays – optional parameter specifying how many days ago the site was visited. If you enter the zero value, no constraint is applied.



ContactManagementContext.CurrentContact.VisitedSite("siteName", 0)


VisitedPage

Returns a bool representing if the contact has visited the specified page.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • GUID nodeGuid – specifies the GUID of the page that has been visited.



ContactManagementContext.CurrentContact.VisitedPage(Documents["/Home"].NodeGuid)


OpenedNewsletter

Returns a bool representing if the contact opened the specified newsletter.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • GUID newsletterGuid – specifies the GUID of the newsletter that has been opened.



ContactManagementContext.CurrentContact.OpenedNewsletter(SiteObjects.Newsletters.CorporateNewsletter.NewsletterGuid)


OpenedNewsletterIssue

Returns true if the contact opened or clicked link in the specified newsletter issue or its variant.

  • object contact – the ContactInfo object.
  • Guid issueGuid – the GUID of the newsletter issue to check.
  • int lastXDays – constraint for last X days (if zero or negative value is given, no constraint is applied).



ContactManagementContext.CurrentContact.OpenedNewsletterIssue(SiteObjects.Newsletters.CorporateNewsletter.NewsletterGuid)


ClickedLinkInNewsletter

Returns true if the contact clicked link in specified newsletter.

  • object contact – the ContactInfo object.
  • Guid issueGuid – the GUID of the newsletter issue to check.
  • int lastXDays – constraint for last X days (if zero or negative value is given, no constraint is applied).



ContactManagementContext.CurrentContact.ClickedLinkInNewsletter(SiteObjects.Newsletters.CorporateNewsletter.NewsletterGuid)


ClickedLinkInNewsletterIssue

Returns true if the contact clicked link in the specified newsletter issue or its variant.

  • object contact – the ContactInfo object.
  • Guid issueGuid – the GUID of the newsletter issue to check.
  • int lastXDays – constraint for last X days (if zero or negative value is given, no constraint is applied).



ContactManagementContext.CurrentContact.ClickedLinkInNewsletterIssue(SiteObjects.Newsletters.CorporateNewsletter.NewsletterGuid)


SubscribedToNewsletter

Returns a bool representing if the contact is subscribed to the specified newsletter.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • String newsletterName – must contain the name of the specific newsletter.



ContactManagementContext.CurrentContact.SubscribedToNewsletter(SiteObjects.Newsletters.Coffee101)


 IsInRoles

 Returns a bool representing if the contact is assigned to any of the specified roles.

  • Object contact – must contain the appropriate ContactInfo object of the contact that is to be evaluated.
  • String roleGuids – specifies the GUIDs of the roles that the contact is assigned to. The GUIDs of the individual roles are separated with a semicolon.



ContactManagementContext.CurrentContact.IsInRoles(SiteObjects.Roles.CMSBasicUsers.RoleGuid + ";" + SiteObjects.Roles.CMSDesigner.RoleGuid)


ActivityLinkedToObject

Returns a bool representing if the activity is linked to the given object by GUID or code name.

  • AcrivityInfo activity – contains the ActivityInfo object of the activity that is to be evaluated.
  • String objectType – specifies the type of the object to which the activity is linked.
  • String objectIdentifier – identifies the object in the given object type by GUID or code name.



Activity.LinkedToObject("cms.form", "SampleForm")


Scoring - Notification email template macros

You can place macros into the text of the Scoring - Notification email template to dynamically load values. The system uses this template for the automatic messages that inform administrators or marketers that a contact has reached a certain amount of score points.

The {% ScoreValue %} expression returns the current number of score points for the given contact.

Additionally, you can access the following related objects and their properties (e.g. {% Score.ScoreDisplayName %} etc.):

  • {% Score %} – ScoreInfo object representing the given score.
  • {% Contact %} – ContactInfo object of the contact that has reached the designated number of score points.

Getting Campaign and A/B test data

If you wish to check whether the current visitor has arrived on the website via a campaign, or passed through a page with an A/B test, you can read the information from the appropriate browser cookie. Use the following macro expressions to get the necessary values from the cookies:

  • Cookies.Campaign – returns the name of the campaign assigned to the visitor.
  • Cookies.CMSAB<A/B test code name> – returns JSON data identifying the page variant assigned to the visitor by the specified A/B test, and information about performed conversions.