Configure the Query String Personalizer App

Follow

Beta Feature Advisory

This article is about an Uberflip Marketplace app that is currently in beta. Like all beta software, this app is provided "as-is" and may contain bugs or may otherwise not work as expected. 

If you would like to try this app and provide feedback to help us improve it, please contact your Customer Success Manager (or Uberflip Support) to request an invitation to the beta program.

What's New

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 Clearbit, 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).
  • On any Hub where you want to use this app, you must enable the setting Include Item tags for Custom Code. You can find this setting under Hubs > Hub Options > Advanced > Content Experience. To enable, check the box next to Include Item tags for Custom Code.

 

About The App

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.

 

Configure App Settings

You configure settings for this app at the Hub level, which means that your settings will apply to the current Hub only.  If you have multiple Hubs, you must configure this app separately for each Hub.

To configure settings for this app, go to Hubs > Integrations > Apps tab. On this tab, open the app's settings by hovering your mouse over the app, then clicking on the Edit (pencil) button.

You can configure the following settings for this app: 

Stream IDs

Required Use this field to specify the Streams that this app will personalize. To add a Stream, type in its Stream ID. Add multiple Streams by separating Stream IDs with commas. All functionality that you configure for this app will be applied to all Streams you specify here, i.e. it's not possible to selectively enable a given feature (Like Filter Items by Tags) for certain Streams but not others.

To find a Stream ID, go to Hubs > Content > Streams tab, click on the Stream, then click on the Metadata tab. The Stream’s Stream ID is listed near the bottom.

Filter Items by Tags

Optional Turn on this setting to personalize the content shown in the specified Stream(s) for each visitor using the values from the URL query string and Item tags. When enabled, the Stream(s) will be filtered so that only Items with tags matching the visitor's query string values are displayed. For example, if the URL that the visitor used to access the Stream contains the query string ?industry=healthcare, then the Stream will be filtered to show Items that you have tagged as relating to the healthcare industry.

To be displayed, an Item must have at least one tag matching any value in the visitor's query string. If an Item has multiple tags, only one tag needs to match the visitor's query string for that Item to be displayed. The minimum number of matching Items that will be displayed is one; if no Items have tags matching the visitor's query string, the full Stream will be shown (all Items).

Tip

To use this feature, you don't need to tag all the Items in your Hub! To get started, try tagging just the Items in the Streams where this app is enabled.

To use Filter Items by Tags, you must add tags to your Items to indicate which query string values they correspond to (i.e. "if a visitor's query string has this value, display Items that have this tag"). The tags must be structured using the following format:

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.

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

Optional Use this setting to specify a custom label for the Previous Item area while viewing an Item. If you do not specify anything here, the default label ("Previous Item") will be displayed.

Next Item Navigation Label

Optional Use this setting to specify a custom label for the Next Item area while viewing an Item. If you do not specify anything here, the default label ("Next Item") will be displayed.

Swap Logo

Optional Turn on this setting to dynamically set the Prospect Logo on Marketing/Sales Streams that use the Banner+Logo template. To use this setting, you must also specify the query string field name where the company name can be found with the Domain/URL Field Name setting (see below).

When enabled, the current visitor’s company will be extracted the query string and used to search Clearbit for a matching logo. If a logo is found, it is automatically placed in the banner beside your own logo. Use the setting Remove Logos When No Match Found to determine what happens if no matching logo can be found.

Note

For this feature to work, you must enable the Banner+Logo template and specify a "default" Prospect Logo under the Appearance tab on any Marketing or Sales Stream where you want to use this app. The default logo will not be displayed, 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

Optional (enabled by default if you have turned on the optional Swap Logo setting). Use this setting to change the behavior of the Swap Logo setting when no matching logo for the visitor can be found on Clearbit. When enabled, both logos will be hidden from the banner. When disabled, the default prospect logo will be displayed beside your logo instead.

Domain/URL Field Name

Required (if you have turned on the optional Swap Logo setting). Use this setting 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 Clearbit for “ACME.com”.

Enter only the exact name of the field, without ? or =, e.g domainName instead of ?domainName=.

Search & Replace

Optional Turn on this setting to dynamically populate placeholders in Hub UI text with values from query strings. Placeholders can be placed in virtually all editable UI text across your Hub. 

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 (see below). 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

The app 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)

Required (if you have turned on the optional Search & Replace setting, at least the 1st field is required; the remainder are optional). Use these fields 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.png

The 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'

Optional When the Filter Items by Tags and/or Search & Replace settings are enabled, turn on this setting to enable an alternative (shorter) format for tags and placeholders. When enabled, you can use qs instead of querystring in tags and placeholders, e.g. qs.[field].[value] rather than querystring.[field].[value].

Enable this setting if you are running into character limits in fields where you are entering tags and placeholders for this app.

Log Mode for Marketers

Optional Use this setting to log basic debugging information in the browser console. When this setting is enabled, the app 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 parsed from the URL query strings will also be shown.

To view these logs, 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>
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.