Zephr User Guide

End-To-End Example

261 views 0

In this example, we’ll guide you step-by-step through setting up your first customer journey with Zephr. Settle in as we take you from integrating Zephr to your site, to creating your User Schema, and building a Feature and Payment offering.

To get this most out of this tutorial, we recommend you have your Admin Console open, so you can complete each step with us.

Example Customer Journey

What we create in this example will cover journeys for users viewing Article content via the Zephr CDN, and will include the following user journeys:

  • Anonymous Users will be required to register to view Article Content
  • Registered Users will be given 2 views per week of Article Content, before hitting a paywall
  • Paying Customers will have full access to content

Step 1: Site Set-Up

First off, navigate to Delivery > Sites. Here you will find a list of Sites already set up to use the Zephr CDN. To add a new Site, click the Add A Site button.

A list of two sites configured on Zephr

On the Add A Site page, give your Site a title. We recommend this being in line with the core URL of your website, so it’s easy to find in your list. For example, in setting up www.zephr.com, we would title our Site ‘Zephr’.


The Domains section is where you determine which domain overrides are exposed to the end-user. Put simply, which URLs will a user be able to use to access your site via the Zephr CDN. This allows you to use Zephr from a number of different domains to access the same origin.

By default, cdn.zephr.com will be available, however, for testing purposes, you may wish to set up {yoursite}.cdn.zephr.com. When you go live, you will also add in all of the domain options for your core site URL, such as www.zephr.com, zephr.com, and sub domains like shop.zephr.com.

When adding Domains, use the slider icon to set which domains should be used for Staging, and which should be used for your Live environment.


In Zephr, your origin site(s) refers to the base website that will sit behind Zephr. This is the version of your site with no user journey rules or transformations, which your domain usually points to. Zephr’s CDN becomes a conduit between your domain and your URL, allowing us to serve your content, create custom user journeys, and add a layer of user authentication.

Set your Default Origin URL to your base origin site, so Zephr can serve the site via our CDN.

If your set up is slightly more complex, Origin Routes allow you to point different requests to different origins. For example, you may serve your /shop section via a different Origin, and you would add this here. Click Add An Origin Route, enter the Base Path, such as /shop, then enter the Origin URL this should be linked to.

For this example, we’ll only need the Default Origin URL set. Once added, click Save.

Step 2: Add User Attributes

Navigate to the Identity Module of your Zephr Admin Console, then click User Attributes.

Here you will find your User Attributes screen, which details the User Attributes you have set up as data points to store against your users.

List of Existing User Attributes

Click the Add A User Attribute button. Here you can set the details for your new User Attribute.

Give your User Attribute a Label, then select the type of field from the dropdown list. In this example, create User Attributes for First Name and Last Name, both of which are Text fields.

Other optional fields include Internal Description to provide an internal reference for administrators and Public Description to explain a field in more detail for front-end users.

Choose if the field is mandatory by ticking the Mandatory Field checkbox.

Note: When considering if a User Attribute should be a Mandatory Field, remember Mandatory Fields need to be provided in ALL cases where a User is being created, whether that’s by the end-user on your website, via API, or via a manual entry in the Zephr Identity area.

If it is mandatory, you’ll need to ensure the field is available on all public Registration Forms. If there are instances where you will not want users to provide this information, we recommend you leave this unchecked. When unchecked, you may still choose to make it required for end-users, by ticking the Required box on your forms.

Creating a User Attribute

Once you’ve entered the relevant details, click Save, or click the arrow next to Save and choose the Save & Add Another option.

Step 3: Build a Feature

Navigate to the Products Module, then select Features. To add a new Feature, click the Add A Feature button.

Name your Feature and, if relevant, provide a short description. For this example, name your Feature ‘Article’ as we will be targeting article content.

Types of Integration

Zephr journeys can be integrated into your site using HTML or SDK integrations. In this example, we’re going to use HTML Features, so select this, then click Continue.

HTML Features work by looking at parts of an HTML document, such as an article body, video, image, or data table on your website. Each feature is wrapped with Zephr tags, or picked up using CSS Selectors. When wrapped in Zephr tags and served via the Zephr CDN, we are able to transform these features, removing them or replacing them with new user journeys, such a registration walls, paywalls, and special offers.

Developer Interface

Once you have named your Feature and selected the type of integration you wish to use, you will see a Developer Interface. This contains the tools needed by a developer to add the Feature to your site.

Firstly, you will see the option to allow web crawlers to access the feature. Selecting Yes will mean the likes of Google Web Crawlers will be able to read your article, regardless of not having an active session or product grants. If you do not want this, select No.

Next, you will see the Site Integration section, which details how to integrate the Zephr Feature with your site.

If you have chosen an HTML integration, you will be given a Feature Tag, like the one seen below, which should be wrapped around the feature of your website.

Zephr HTML Feature Tags

If you have already integrated the Zephr Feature Tags onto your page, you can check your integration by selecting Check Site for Feature Tag. This will crawl your site to check the Feature Tag is present, and warn you if it cannot be found.

No Feature Tags Found

If you are yet to add the Feature Tags to your site, do this now, or alternatively select the CSS Selectors option and add the CSS Selector used to identify an Article within your page. For example, div.article-content.

Once you’re happy with your Developer Interface set up, select Update & Lock. This will ensure it is not accidentally updated during future rule changes. Once locked, it can be accessed below the Rules Builder.

Using the Rules Builder

The Zephr Rules Builder is where you decide what your site visitors see.

Across the top, you will note a slider for Anonymous, Registered, and Customer user types. Toggling between these will give you a blank rule canvas to build a bespoke journey for that user type.

The Rules Builder also has a decision bar, detailing the different decision points and outcomes available to use, and a rule canvas.

Each journey begins with a Page View Node, signifying when a user views a page which includes your Zephr Feature. To build your user journeys, drag decisions from the top decision bar onto your rule canvas and join the dots to build your user journeys.

First, we’ll focus on the Anonymous user journey. In this example, all Anonymous users (users without an active session) will see a Registration Wall across Article Content.

Step 4: Build a Registration Form

Registration Forms are created as Components of your Feature Outcomes. To begin, navigate to Outcomes option in the rules builder palette, then click Add Outcome. Name your Outcome ‘Registration Form’ then scroll to the Components section. Click Add A Component, then click the Add button in the Form section.

The next page is where you create your registration form. Along the top, you’ll see tabs for Form Fields and Custom CSS.

Building a Form - Form Fields & CSS

Form Fields lets you add the fields you wish to have on your form. These come from your User Attributes, which we set up before.

Custom CSS allows you to style your form to suit your brand.

Under Form Fields, give your Form a Title, and an optional Description. For Type, select Registration.

You will have the option to enable Login Providers for social sign on. Read our Login Providers guide for more information on enabling this feature.

Below this, the MultiStep Form section lets you choose which fields are available on your Form. Select Registration to choose the fields that are available on your Registration From

You can update the fields as described in Define a Registration Form. You can add user attributes, custom text and further sections in your multistep Registration Form.

These fields will now display within your form. Drag and drop each field until you are happy with the order, add dividers to display form fields by category, and set a user attribute field as mandatory by using the Required slider.

When you’re happy with your form, click Save.

You will return to the Outcome page and will see your newly created Registration Form under the Components section.

Components Section Showing Feature and Registration Form

Add a Lead-In by clicking ‘Hide Some Content’. A modal will display asking you to select how many words of your article to show before your Registration Form. Select 20 words, then select the Fade Out style and click Save.

When your Lead In and Registration Form are ready, click Save to save your Outcome and return to your Rule Canvas. You will see your Registration Form as an outcome in your decision bar. Drag this onto your canvas and connect it to your rule by attaching it to the Page View node, so that all anonymous users see a registration form when viewing article content.

Example Customer Journey - Anonymous Users

Once your Outcome has been created, you can edit and delete it in the Outcomes section, below your rule canvas.

Shows Outcomes Section Below Rules Canvas

Save your progress by clicking the Save button below.

Step 5: Create a Product

Now we’ve created an anonymous user journey which converts user registrations, it’s time to build a journey that drives paid subscriptions. We’ll do this by creating a Product, and adding a paywall to our rule.

In Zephr, a Product is a way of grouping features together into one package and is used to provide your customers with access to your content.

Products can be monetised using third party payment providers, with Zephr out-of-the-box payment forms available to build quick and easy paywalls.

To create a Product, navigate to Products > Catalogue, and select Add A Product.

Adding a Product - Add Product Screen

Give your Product a Title, and an optional Description.

Select Features

Specify the Features the Product is relevant to. This is so when users access the Features selected, and have the Product granted to them, they will be considered Customers, and follow the Customer user journey created within that Feature rule. For this example, tick the Article feature you’ve just created.

Adding a Product - Selecting Features

If the Feature is available across multiple sites, you can choose to limit the Product to be available on specific sites. To do this, click the Add Sites & Site Groups button, and select the relevant sites.

Adding a Product - Specifying Sites

Payment Options

To add Payment Options for your Product, you will need to link Zephr to a payment provider. Zephr integrates out-of-the-box with Braintree, Stripe and Chargify.

If you haven’t done this yet, read our Payments guide. If you’ve set this up already, continue reading.

Payment Options determine the way your users can pay to gain access to the Product. For example, an Article Subscription may offer a plan to gain access for £10 for one month, or a plan to gain access for £5 per month, for 12 months. If you are using Stripe, your payment plan may also vary in price each month. Read the ‘Scheduled Payment Plan’ section below for more details.

First, select Add a Payment Option.

Regular Plans

In most cases, the ‘Type of Plan’ you select will be set to ‘Regular’. A Regular plan is available when you are integrating with Braintree, Stripe, or Chargify.

This allows you to find payment plans already set up within your payment provider, who will manage the subscription on your behalf and charge the user as needed.

Enter the name of the payment plan, as it has been set up within your payment provider, or click Browse Payment Plans to find it in a list of payment plans you have configured within your payment provider.

Products - Select Payment Option

Once you have selected the Payment Plan, you will see more information regarding the plan details. Most of these – the Plan Name, Product Price and Billing Period – cannot be edited, as they are pulled directly from your payment provider.

You will, however, have the opportunity to edit the Billing Cycles. Here you have two options:

Recurring Billing Cycles will continue to charge the user for as long as the Payment Plan states within your payment provider settings. For example, if you have a Braintree Payment Plan set up to bill perpetually, or for 12 consecutive months, payments will follow this plan.

Custom Billing Cycles allow you to override the number of billing cycles set within your payment provider. For example, a Braintree Payment Plan may be set to bill perpetually, but you could override this in Zephr to end after three billing cycles.

Payments - Recurring Payment Billing Cycles

Once you have set your Billing Cycles, click Add.

Your Payment Options will display below the Add A Payment Option button, with details of the Plan Title, Cost, Currency, Billing Period and number of Billing Cycles. Clicking the kebab menu will allow you to either edit or delete the payment option.

Payments - Viewing Payment Options

Scheduled Payment Plans

If you are using Stripe, you will also have the option to select a Scheduled Payment Plan.

Scheduled Payment Plans allow you to create a payment plan with staggered pricing. For example, offering a one-year subscription for £10 per month for the first three months, after which the customer will pay £20 per month for the remaining nine months of their term.

Creating a Scheduled Payment Plan is similar to the way you create a Regular Plan.

Start by selecting the Scheduled Payment Plan option under the Type of Plan heading and give your Scheduled Payment Plan a title.

Following this, select the first relevant plan from your list of linked plans. This should be the plan with the pricing relevant to the first part of the schedule.

Products - Scheduled Payment Plan - First Payment

In the image above, you’ll note we selected Plan 4 – a plan charging users £10 per month. By setting the Custom Billing Cycles to 3, we ensure the user is charged £10 per month, for the first three months.

Next, click Add To Schedule. Repeat this process with the other Payment Options you wish to include in your Scheduled Payment Plan.

You’ll note that once each payment option is added, they will appear in the Subscription Schedule below. This details the Plan Name, Price, Currency, Billing Frequency, and the number of Billing Cycles. You can drag and drop Payment Options within the Subscription Schedule to reorder them.

Products - Scheduled Payment Plan - Second Payment

In the example above, customers using this Scheduled Payment Plan will be charged £10 per month for the first three months, followed by £20 per month for the remaining nine months.

Scheduled Payment Plans can also include Recurring Billing Cycles, where a user is charged until the end of the payment cycle set by your payment provider, however, this option must be placed at the end of your Subscription Schedule.

Once your payment options are in place, click Add.

Your Payment Options will display below the Add A Payment Option button, with details of the Plan Title, Cost, Currency, Billing Period and number of Billing Cycles.

Products - Payment Options - Scheduled Payment Plan View

Clicking the kebab menu will allow you to either edit or delete the payment option.

Once your payment options are in place, click Save.

Step 6: Create a Trial

Before users convert to a paid subscription, it’s a good idea to show them the quality of your content by providing a free trial.

Zephr offers the ability to create Trials for your Anonymous and Registered users.

A trial gives a user limited access to a Feature, on a one-off or recurring basis. For example, you may offer users three free views of article content when they register. This would be managed as a trial.

In this example, we’ll offer Registered Users two views of Article content per week, before they see a paywall.

Creating a Trial in a Feature

Trials can be used in both Features and Redirects, and are implemented in the same way across each. For this example, we’ll use your Feature rule for Articles.

Navigate back to the Products Module and select Features, then click into your  Article Feature and click the version of the rule you saved previously so we can add to that rule. Use the slider to set the canvas to the registered user journey.

Select Access, then drag the Trials node onto your rule canvas.

Number of Views

In the modal that opens, first set the number of views you would like for your trial. For example, setting this to two will mean a user receives two views of article content, before seeing a different outcome.

Recurring Frequency

Next, set your Recurring Frequency. One-Off means the trial will not recur, whilst Daily, Weekly, Monthly, and Custom allow the trial to reset on a recurring basis. This is helpful if you offer ‘x’ free views of content per month. For this example, select Weekly.

Creating a Trial - Set Up

Trial Type

Set your Trial Type. Select Unique if you would like a user to be able to read an article multiple times without it removing a trial view each time, otherwise select Page View. You can also choose to count pages with different query parameters separately.

Remaining Trial Count

Remaining Trial Count allows you to add additional outputs to your Trials node on your rules canvas. These additional outputs allow you to alter the customer journey based on the number of remaining views each user has, but we won’t use that for this example.

When complete, click Save.

Connecting Your Trial

Once your trial is on the canvas, connect it to the rest of your rule accordingly.

The In Trial output should be connected to the Outcome users should see when they have access to trial views – in this case, we’ll use the Show Articles option so users with remaining views can read the article.

The Trial Expired output should be connected to the outcome users should see when they have finished their trial – in this case, a paywall which we’ll create in the next step.

Step 7: Build a Payment Form

Payment Forms in Zephr are your out-of-the-box way to add a Paywall to your site. Choose your Product, select your Payment Options, and Zephr will do the heavy lifting to build a form for your end-users to buy your products with.

To create a payment form, select the Add Outcome option from the decision bar again.

Name your Outcome ‘Payment Form’, then scroll to the Components section, select Add a Component, then click the Add button below the Payment Form option.

This will take you to the Add Payment Form page. Along the top, you’ll see tabs for Payment Options and Custom CSS.

Payment Form Tabs

Custom CSS allows you to style your form to suit your brand. Payment Options is what we’ll focus on for this example.

First, complete the Details for your form, by giving it a Title and optional Description.

Next,  select the product you want available for purchase on the form. If you haven’t set up any Products yet, take a look at our Products guide.

Select the Product you wish to associate with the form from the dropdown. Below, you will see a section for Payment Options. Click Add a Payment Option and a modal will open.

Under the Select a Plan field you will see a list of payment options linked to the product you have selected on the previous page. Select an option, and write a description. This description will be shown to your end-users when they view and choose this payment plan.

Add Payment Option Modal

Click Add.

Your payment option will now be available on the payment form screen. Repeat this process to add more payment options until you’re happy with the options available on your form.

NOTE: If your payment option is part of a Scheduled Payment Plan, end users will see the price for the first billing cycle on the payment form. As such, please ensure you provide a clear description of when and how the price will change.

The Recommended toggle will add a Recommended tag to each product it is checked against. For example, if you offer a monthly plan at $10 per month, and an annual payment option at $100 per year, you may wish to ‘Recommend’ the annual option as it is the best value for money.

Example Payment Options

Once complete, click Save, and complete the rest of your Outcome as usual. We recommend creating a lead-in in line with what you created for your anonymous user journey.

When complete, save your Outcome and drag the Paywall Outcome onto your rule canvas, connect it to your user journey as seen below.

Example User Journey - Registered Users

Users hitting the paywall will see a payment form connected to your payment provider. Once payment is accepted, the registered user will be granted the corresponding product in Zephr, and become a customer.

Example Out Of The Box Payment Form

For the Customer journey, select Outcomes, then drag Show Article onto your Rule Canvas. Connect this to the page view node so all customers with the relevant product can view your article content.

Example User Journey - Customer

When you’ve built journeys for each of your user types, click Save.

Step 8: Publish your journey

Zephr Rules are versioned, so once you’ve saved your Feature, you will be taken to a page detailing any versions of this Feature that are available to publish.

List of Available Features and Actions

Click the version number to view or edit any of these rules, or click Add a New Version to start from scratch. Edited rules will always save as new versions, so there’s no need to worry about losing old versions.

If you want to delete a version, click the Delete button next to the relevant version number.

Your Feature’s version page also provides information on which rule is currently in Staging or Published to your live site.

Published rules are tagged as Live in the Status column, versions in Staging are tagged as Staged, and versions which have previously been Live have a status of Previously Published.

To publish a rule, you will first need to promote it to Staging. To do this, click the Stage button in the Actions column, next to the relevant version. You’ll be able to visit the Staging Domain you set up in the Sites section to test your rule.

When you’re happy with your rule in Staging, click Publish, and we’ll make your rule Live. Only one version per Feature can be made Live at one time. View your customer journey by visiting the Live Domains you set up in the Sites section earlier.