QueryString Personalizer: User Guide

Follow

What's New

Release Notes (click to expand)

Oct 5, 2021

  • Added ability to configure certain app settings at Stream level.
  • Added Stream-level Enable setting to activate the app on a Stream.
  • Removed the Stream ID setting, as it has been replaced by the Stream-level Enable setting.

Apr 8, 2020

  • Added details on how to use the Show Always Tag under the Filter Items by Tags option.

Apr 2, 2020

  • Added a Best Practices section.

Mar 18, 2020

  • Added a For Developers section and details about the ufPersonalizerCallback function that developers can leverage.

Mar 3, 2020

  • Added a Remove Logos When No Match Found option to provide more control over the behavior of the Swap Logo option.
  • The app will now also work on Hubs running the new Uberflip front end engine.

 Feb 26, 2020

  • Added a Log Mode for Marketers option which enables a simplified debug logging mode.

Feb 3, 2020

  • Changed the format for placeholders from {{placeholder}} to {placeholder} (i.e. from double curly brackets to single curly brackets) to allow them to be used in custom code blocks.
  • Changed the behavior of Swap Logo. Previously when this setting was enabled and no logo match for the current visitor was found on Query String, the app would display the "fallback" visitor logo (if configured) in the banner instead. Now, the app will hide both logos from the banner, so it is no longer necessary to set a "fallback" visitor logo.

January 23, 2020

  • Added support for filtering at the Item level. While viewing an Item, the app can now filter the additional Items shown in the carousel and Next Item/Previous Item flyouts.
  • Added the ability to customize the labels of the Next Item/Previous Item flyouts.
  • Added a Short Form option that allows for the use of qs instead of querystring in tags and placeholders.

January 16, 2020

  • Split the single field for defining Search & Replace values into ten separate fields to help avoid character limit issues.

January 6, 2020

  • Added the ability to insert specially-formatted placeholders in fields that checked for valid URLs, such as Link CTA Link Action fields.

 

Before you begin

  • This app uses query strings to personalize Streams, so you must share Stream URLs that contain query strings (and appropriate values) for it to work. The app will still work on Streams accessed without a URL containing query string values, but will only display default values in this case (provided you have defined default values).
  • If your Hub uses Front End V2, you must also install the Compatibility Pack app. If you are not sure if your Hub uses Front End V2, see this article for help.

 

About QueryString Personalizer

This app personalizes selected Streams using query string values from the URLs used to share those Streams. It can:

  • Dynamically filter a Stream to only show Items that match query string values contained in the Stream’s URL (using tags)
  • Automatically populate a visitor’s organization logo on Streams that use the Banner+Logo template (if the organization is specified in the query string)
  • Automatically insert query string values from the URL used by the visitor into variables placed in Hub text: titles, descriptions, body text, CTAs, etc.

 

Setup: Enabling Item tags for Custom Code

QueryString Personalizer uses Uberflip Item tags to personalize content for individual visitors. By default, these tags are only displayed in the Uberflip app, and are not included when an Item is viewed in the Hub's front end. To make these tags available to app like QueryString Personalizer, you must enable the setting Include Item tags for Custom Code.

Info

This setting is Hub-specific, so you must enable it separately in each Hub where you want to use Query String Personalizer.

  1. Log in to your Uberflip account and use the Hubs menu to select the Hub where you want to enable the setting.
  2. Click on Hub Options > Advanced.
  3. Under the section Content Experience, check the box next to Include Item tags for Custom Code:
    image.png
  4. The change will be saved automatically, and will take effect immediately.

 

Configuring the QueryString Personalizer app

To use QueryString Personalizer in your Uberflip account, configure the app's settings. These settings control the app's functionality, and how it is applied to your Hubs and Streams.

You can configure settings for QueryString Personalizer at the Account Level, the Hub Level, the Stream Level, or all three:

  • Any settings you configure at the Account Level will apply to all Hubs in your account.
  • Any settings you configure at the Hub Level will apply to that Hub only. If you have also configured Account Level settings, Hub Level settings will override them for that specific Hub.
  • Any settings you configure at the Stream Level will apply to that Stream only. If you have also configured Account and/or Hub Level settings, Stream Level settings will override them for that specific Stream.

Some of this app's settings can only be configured at certain levels. The level(s) at which any given setting are available are indicated beside each setting below.

For instructions on how to access Account, Hub, and Stream Level settings for any Uberflip Marketplace app, see Configure settings for Uberflip Marketplace apps.

Enable

Available at: Stream Level

Optional This setting is used to enable the QueryString Personalizer app for the current Stream.

When this setting is turned on, the app will be active on the current Stream, using the settings you have defined at the Stream Level. If a setting is not defined at the Stream Level, the app will use the Hub Level settings (if set), or otherwise the Account Level settings (where no Hub Level setting exists).

  • This setting is only available at the Stream Level, and is turned off for all Streams in all Hubs in your account by default.
  • To use the QueryString Personalizer app to personalize a Stream, you must turn on this setting for that Stream individually.
  • Until you have turned this setting on for at least one Stream in your account, the QueryString Personalizer app will have no effect on your account (even if the app has been fully configured at the Account and/or Hub Level).

Filter Items by Tags

Available at: Account Level | Hub Level | Stream Level

Optional This setting is used to control QueryString Personalizer's dynamic filtering functionality.

When this setting is turned on, the app will filter the Items in the specified Stream(s) so that only Items tagged as relevant to the current visitor are displayed. For example, if a visitor's QueryString data indicates that their industry is Financial Services, then the Stream will be filtered to show Items that you have tagged as relating to the financial services industry.

  • In order for this functionality to work, you must set up QueryString Attribute Tags in your Uberflip account, and add them to all Items in Streams where QueryString Personalizer is active. See Using Attribute Tags for more information.
  • When Filter Items by Tags is enabled, an Item must have at least one Attribute Tag matching any attribute in the visitor's QueryString data to be displayed. Items that do not have at least one matching Attribute Tag (or which have no Attribute Tags) will not be displayed.
  • If an Item has multiple Attribute Tags, only one of these tags needs to match the visitor's data for that Item to be displayed.
  • By default, the minimum number of matching Items that will be displayed is one. If no Items in a Stream have Attribute Tags that match the visitor's QueryString data, all Items in the Stream will be shown (to avoid showing the visitor an empty Stream).
    • Using the Show Always Tag changes this behaviour. If you use the Show Always Tag, then only Items that have the Show Always Tag will be displayed in this situation (rather than all Items in the Stream).
  • When a Stream is filtered, the order in which the Items are shown will still be the same as in the original (unfiltered) Stream, except with the filtered Items hidden. For example, if five Items in a Stream are in the order 1-2-3-4-5 and Items 1 and 4 are filtered out, the Stream will still display the remaining Items in the order 2-3-5.

Tip

If you want to use Filter Items by Tags, it's not necessary to tag all the Items in your Hub! To get started, try tagging just the Items in the Streams where this app is enabled.

Using Attribute Tags

To use the Filter Items by Tags functionality, you must add Attribute Tags to all Items that appear in Streams where QueryString Personalizer is enabled. Attribute Tags are specially-formatted tags which you use to indicate to QueryString Personalizer which content Items should be displayed if a visitor has a given attribute in their QueryString data.

To apply an Attribute Tag to an Item, simply add it to the Item in the same way as a normal Item Tag (see Use Tags on your Items for instructions). Attribute Tags use the following structure:

querystring.[field].[value]

Within this basic format, replace [field] with the query string parameter, and [value]with the parameter's desired value. For example, the tag querystring.industry.healthcare would indicate that the tagged Item should be displayed if the URL contains the query string ?industry=healthcare, and would therefore be applied to Items relevant to that topic.

Note that field names and values in tag names must match values in query strings exactly: any spaces, parentheses, etc. that exist in the query string must also exist in the tag.

You can choose to always display certain Items, regardless of the visitor's QueryString data. To do this, use the Show Always Tag:

querystring.show

This tag is created automatically when you install QueryString Personalizer. To use it, simply add it to any Items that you want to always be displayed in Streams where QueryString Personalizer is active (provided the Item has been added to the Stream). This is useful for content that is relevant to a very wide audience and should be shown to all visitors, as well as to avoid instances where only one or two Items would be shown in the Stream based on Attribute Tags alone.

If you use the Show Always Tag, keep in mind that the filtered Stream will still respect the Item order set for the full Stream. As a result, we recommend placing Items with the Show Always Tag either at the beginning or end of the Stream (depending on the content).

Important

Do not delete the Show Always Tag from your Uberflip account, even if you don't use it on any Items! QueryString Personalizer requires this tag to be present to enable key app functionality.

Note

This app filters not just Items on the main Stream page, but also the additional Items displayed when viewing an Item in that Stream. While viewing an Item, the Next/Previous Item area and the Other Content in This Stream carousel will be filtered in the same way as the main Stream page:

  • For the carousel, filtered Items will take priority, and any additional free slots in the carousel (after all filtered Items have been displayed) will be filled with non-filtered Items from the same Stream
  • If no next or previous filtered Item is available, the Next/Previous Item area will be hidden

Previous Item Navigation Label

Available at: Account Level | Hub Level

Optional This setting is used to specify a custom label for the Previous Item area while viewing an Item.

  • To specify a custom label for the Previous Item area, enter it into the field.
  • If you do not specify a custom label (i.e. if you leave the field empty), the system default label ("Previous Item") will be displayed.

Next Item Navigation Label

Available at: Account Level | Hub Level

Optional This setting is used to specify a custom label for the Next Item area while viewing an Item.

  • To specify a custom label for the Next Item area, enter it into the field.
  • If you do not specify a custom label (i.e. if you leave the field empty), the system default label ("Next Item") will be displayed.

Swap Logo

Available at: Account Level | Hub Level | Stream Level

Optional This setting is used to control QueryString Personalizer's dynamic logo functionality.

When this setting is turned on, the app will use a visitor's QueryString data to search Clearbit's Logo API for the logo of the visitor's organization. If a logo is found, it is automatically inserted into the Prospect Logo space on Marketing/Sales Streams that use the Banner+Logo template.

Note

For the Swap Logo functionality to work, you must enable the Banner+Logo template and specify a "fallback" Prospect Logo under the Appearance tab on any Marketing or Sales Stream where you want to use this app. The fallback logo will not be displayed if QueryString Personalizer can find a logo for the visitor, but this feature will not activate if no logo is set. We recommend using a generic logo for this purpose (e.g. a logo that just says "You" or similar).

We also recommend specifying a default Banner Title under the Appearance tab to be displayed in case no logo is found and the logos are hidden from the banner. If you do not specify a Banner Title, only a blank header (or Banner Image, if specified) will be shown.

Remove Logos When No Match Found

Available at: Account Level | Hub Level | Stream Level

Optional (enabled by default if you have turned on the Swap Logo setting). This setting is used to control the behavior of the Swap Logo setting in cases where no matching logo for the visitor can be found.

If no matching logo is found:

  • When this setting is turned on, both logos will be hidden from the banner.
  • When this setting is turned off, the "generic" Prospect Logo you set for the Stream will be displayed.

Domain/URL Field Name

Required (if you have turned on the optional Swap Logo setting). This setting is used to to specify the query string field name whose value should be used to search for a company logo.

  • For example, if you set this to domainName, and the URL includes ?domainName=ACME.com, then the app will search Query String for “ACME.com”.
  • Enter only the exact name of the field, without ? or =, e.g domainName instead of ?domainName=.

Search & Replace

Available at: Account Level | Hub Level | Stream Level

Optional This setting is used to control QueryString Personalizer's dynamic text replacement functionality.

When this setting is turned on, QueryString Personalizer will dynamically populate any variables (placeholders) you have placed in text across your Hub with values from the visitor's QueryString data, for example their company name, industry, or location.

  • You can place variables in virtually all editable text across your Hub, including Stream, Item and CTA copy text. See Using Search & Replace variables for more details.

Using Search & Replace variables

To use the Search & Replace functionality, insert specially formatted variables into editable text in your Hub, such as body text, titles, descriptions, etc. Variables must be placed within curly brackets ({ and }), and must use specific formatting.

To insert a placeholder, use the format {querystring.[fieldname]}, replacing [fieldname] with the desired field name you have defined in the Search & Replace Fields and Empty Values section. For example, a user with the query string ?firstName=John would see "John" anywhere you have inserted the placeholder{querystring.firstName}.

Note: Placeholders in URL and Email Fields

QueryString Personalizer can also populate placeholders inserted into URL and email fields, such as the Link Action field on Link CTAs. Because most of these fields in Uberflip have validation, you must use a special format for placeholders in these fields to ensure that the placeholder is not rejected by the validator.

For fields that validate email addresses or URLs, do not use the standard placeholder format (as above). Instead, use the following formats:

  • Email Fields: replace@querystring.[fieldname]
  • URL Fields: replace.querystring.[fieldname]

As with the standard format, replace [fieldname] with the desired field name you have defined in the app settings. Note that the special formats are only required in fields with URL validation; URLs in normal text fields (unvalidated) can use the standard format.

When this setting is enabled, you must use the Search & Replace Fields and Empty Values settings to specify which query string field names you want to use in placeholders, as well as which default values to use if the field name is not present (or has a blank value).

Search & Replace Field and Empty Values (1st to 10th)

Available at: Account Level | Hub Level

Required (if you have turned on the optional Search & Replace setting, at least the 1st field is required; the rest are optional). These fields are used to specify the query string field names you want to use as placeholders.

  • If you reference a query string field name in a placeholder, but have not specified it in one of these fields, then the placeholder will not work (will not be replaced with a value from the query string).
  • To use this setting, use each individual field to specify both the query string field name and a default value to be used in case the field name does not exist in the URL (or lacks a value).
  • Field names and their default values must be formatted as JSON objects, i.e. as a key-value pair. Use this format:fieldName:'Default Value'
  • Define only one field name/value pair per setting text field, for example:

    image.pngThe example setting shown above would allow you to use the field names firstName, companyName, industryusecase and repName as placeholders, and would insert the appropriate value (e.g. You, Your Company, etc.) anywhere that the corresponding placeholder appears if there is no value present in the URL.

Short Form: Use 'qs' instead of 'querystring'

Available at: Account Level | Hub Level

Optional When the Filter Items by Tags and/or Search & Replace settings are enabled, this setting can be used to enable an alternative (shorter) format for tags and placeholders.

  • When this setting it turned on, you can use qs instead of querystring in tags and placeholders, e.g. qs.[field].[value] rather than querystring.[field].[value].
  • Turn this setting on if you are running into character limits in fields where you are entering tags and placeholders for this app.

Log Mode for Marketers

Available at: Account Level | Hub Level | Stream Level

Optional This setting is used to log basic debugging information in the browser console.

When this setting is turned on, QueryString Personalizer will record information about what the app is doing in the browser console, such as what has been filtered and why. In addition, the data the app received from the current visitor's query string will also be shown.

  • To view these logs that are generated when this setting is enabled, you must open the console in your browser. How you do this will vary based on the browser you use; for instructions on how to open the console in Chrome, see this article from Google.

 

Best practices

When using this app, we recommend the following for best results:

  • For Streams and Items that you intend to share on social media, avoid using Search & Replace placeholders in the Title and Description fields. These fields are used to populate the Open Graph and Twitter Card tags that social platforms use to generate link previews, and any text you put in them will appear in the preview — including the placeholder text itself, e.g. {querystring.companyName} instead of the name of the relevant company name.
  • For Marketing and Sales Streams, we recommend enabling the Banner+Logo template under the Stream's Appearance tab, as this will allow you to use the Swap Logo setting. If you select this template, you should also enable the Hide Stream Title option and specify a Banner Title (also under the Appearance tab). There are two benefits to doing this:
    • If the Remove Logos When No Match Found option is turned on and no logo matches are found, the Banner Title will be shown on the banner instead (rather than an empty banner image).
    • If you intend to share the Stream on social media, you can put a placeholder in the Banner Title field (as this isn't shown in the social media preview), but not in the regular Stream Title field (which is shown on social media). In other words, this allows you to personalize the title that a visitor to the Stream sees, without the placeholder text appearing when the same Stream is shared on a social media platform.
  • For all Streams and Items that you don't plan to share on social media, but which you expect to be indexed by Google, we recommend using the SEO Title and SEO Description fields. These allow you to specify alternative titles and descriptions for your Streams and Items when they appear on Google search result pages. You can use these fields to ensure that any placeholders you put in a Stream's or Item's title/description do not appear when that Stream or Item appears on Google.

 

Troubleshooting

If you experience problems with this app's functionality, this may be due to corrupted data. To resolve the issue, try clearing your browser's cache (or try using the app in Incognito Mode to see if that resolves the issue).

 

For developers

Because this app manipulates a large portion of Stream and Item pages, a race condition can occur, which can cause other JavaScript custom code running on the same page to malfunction. 

If your JS code performs other manipulations on pages where this app is active, you should ensure it runs after the app to avoid problems. To help you do this, a callback function is built into the app that will be called once the app has finished executing its own code.

To leverage the callback function, create a function named ufPersonalizerCallback in your own custom code and place your JS inside it. For example:

<script>
var ufPersonalizerCallback = function(){
/** Your JS **/
};
</script>
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.