API documentation

# Embedding functionality

There are a bunch of methods for generating iframes to be included on your site so you can embed functionality easily. Common parameters are:

  • profile which is a short lower-case descriptive string to use for the URL, e.g. if your business entity name is "Foo Bar" it will typically be "foobar"; you can find it in your customer service settings inside Iteras as "URL ID".
  • cssclass which sets a CSS class on the body element inside the iframe, in case you need to customize a particular iframe.
  • preauth which given a pre-auth token causes a given customer to be logged in automatically.
  • next which overrides what page to redirect to after the action is done, e.g. after ordering

Note that logging in to the self-service does not log you in to a paywall and vice versa. Paywall sessions are usually long, to reduce hassle for paying customers, whereas access to the self-service should usually be kept short as people only rarely need to manage their data.

# Customer self-service iframe 

Iteras.selfserviceiframe({ profile: "myprofile" })

Generates an iframe with the customer self-service pages. The first page will usually be the login page, followed by an index page that provides an overview of the information stored on the customer, subscriptions and any unpaid invoices.

Note that logging into the self-service does not automatically log in to the paywall and vice versa. The two systems are kept separate for security reasons.

# Ordering form iframe 

Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXXX" })

Generates an iframe with an ordering form that allows a prospective customer to place an order.

  • orderingid is the URL ID for the ordering form inside Iteras. It’s usually either a randomly generated string or something descriptive that you have chosen.
  • next is an optional URL to redirect to after the order is completed.
  • prefill is a list of fields and their values that should be filled out by default when the form is displayed. See example below.
  • autologinredirect automatically redirects the user to the login screen if their email is recognized.
  • startwithlogin will start the ordering flow with the login screen. This can come in handy if you are sending users with an existing account to an ordering form.

By using the prefill parameter, you can prefill any field configured as permissible for prefilling in the ordering form. Prefilling products can also accommodate a list, allowing the selection of multiple products. For campaigns, use campaign IDs as the product identifiers, and for individual products, use the external product IDs.

Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXXX", prefill: { products: ["campaign_id", "product_external_id"], utm_source: "socialmedia" }})

When using ordering forms that require an ordering code, the user journey is made smoother by adding a step in front that determines which ordering form should be showed for an ordering code. This iframe is added with:

Iteras.orderingcodeiframe({ profile: "myprofile" })

# Paywall login iframe 

Iteras.paywalliframe({ profile: "myprofile", paywallid: "XXXXXX", next: "/" })

Generates an iframe with page to login to the paywall. The paywall ID can be found in the paywall settings. "next" is a path to redirect to upon succesful login in case there isn’t a more appropriate redirect known (the iframe looks for an iterasnext GET parameter in the page it is inserted.

The paywall login page uses the iframe to set a cookie on your domain with paywall access info - see the paywall section for details. This cookie does not log the visitor into the self-service.

Note that paywall login iframe is intended to redirect to another page. If you don't give it redirection information or just somehow redirect to the same page so it is rerendered, it will show the login form again. Don't get confused! If your browser has the cookie, you're logged in.

You can set the required access level with "access" (see the paywall section for more info), e.g.

Iteras.paywalliframe({ profile: "myprofile", paywallid: "XXXXXX", access: "user" })

In case you need to login to multiple paywalls at the same time, e.g. if each paywall walls off a separate section, you can specify a list of paywall ids instead of a single id, e.g.:

Iteras.paywalliframe({ profile: "myprofile", paywallid: ["XXXXXX", "YYYYYY"], next: "/" })

IP-based authentication: IP-based access control works the way that the paywall iframe will automatically check the IP address and log in visitors with IP-based access without going through the usual password flow. When such a visitor is logged in, the rest of the flow then works as usual.

# Inserting an iframe

The iframe methods generate a string with HTML that you can either insert directly in the page with document.write, e.g.

<script>
  document.write(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
</script>

or you could use a framework, e.g. with jQuery

<div id="ordering-iframe-container"></div>
...
<script>
  $(function () {
    $("#ordering-iframe-container").append(Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" }));
  });
</script>

The iframe will automatically resize its height based on the height of its content. Note that for this to work, the iteras.js script must be included on the page (as would normally happen when you use the API).

If you want to control the height or width yourself, we recommend you put the iframe (or document.write <script>) inside an element you control yourself and set max-width/max-height on that with CSS. This prevents conflicts with the styles applied by the Iteras API.

# Usage tracking

Iteras does not track user behavior out-of-the-box since this requires consent from the user. If you have consent the following tracking functionality can be used to send information from within the iframe to the parent frame. It is a message bridge which combined with code added to the iframe lets you track any behaviour within Iteras iframes, both self-service or ordering forms.

Tracking code is added to the iframe through customer service configuration in Iteras. Simple page load tracking can be done like this:

<script>
 $(function() {
   Iteras.track({ "type": "page-load", "page": $("body").data("page") });
 });
</script>

If only page loads in a specific section is needed, like during ordering, the code could instead be:

<script>
 $(function() {
   if ($("body").hasClass("ordering-base"))
     Iteras.track({ "type": "page-load", "page": $("body").data("page") });
 });
</script>

The Iteras.track function bubbles a Javascript event out of the iframe with the supplied data. Listening to the above event outside the iframe could look like this:

<script src="https://app.iteras.dk/static/api/iteras.js"></script>
<script type="text/javascript">
  var ordering = document.getElementById("ordering");
  ordering.innerHTML = Iteras.orderingiframe({ profile: "myprofile", orderingid: "XXXXX" });
 
  ordering.querySelector("[name^=iteras-iframe]").addEventListener("iteras-track", function (e) {
    console.log("Got tracking event:", e.detail);
  });
</script>

The event will bubble all the way out, so to catch tracking events from all iframes on a page the event handler can be attached to document:

document.addEventListener("iteras-track", function (e) {
  console.log("Got tracking event:", e.detail);
});

To sum up, tracking is done by adding code to the iframe through the customer service configuration that observes the users behavior and sends that information out of the iframe with Iteras.track() to your website where it can be collected.

# Common questions/problems

# The iframe has sizing problems/looks weird?

It’s common to end up with a bunch of CSS files to style various things. There is probably something in one of those files with a rule that accidentally applies to the Iteras iframes. Rules to look out for are both rules on iframes and rules on the parent elements of the Iteras iframes, e.g. if the iframe doesn’t automatically increase its height, there could be a rule that restricts the max height of the elements where the iframe is embedded.

To debug this, inspect the inserted iframe with the developer tools in your browser and see what rules are applied to the element and its parents.

# How do I control the style of the iframe itself, e.g. width/height?

Don’t. Put it inside a wrapper element (e.g. a <div>) and apply your styles to that element. This prevents conflicts with the styles applied by the Iteras API.

# How do I control the looks of the iframe contents?

Due to separate security contexts in the browser, the iframe content ignores outside rules. So you have to include your CSS through the website customization fields in the customer service settings inside Iteras. You can include the styles inline or through a link to a CSS file hosted on your own site.

# How do I apply different styles for different iframes?

Use the "cssclass" parameter when generating the iframe, it sets a CSS class on the body element inside the iframe so you can the hook up on that.

# When I log in to the paywall, I am not allowed to access to the self-service?

The self-service and the paywall authorizations are kept separate, for security reasons. Usually, paywall access is frequent, must be convenient and is at the same time relatively safe from the point of view of the customer. Self-service usage is infrequent and allows destructive operations.

← Overview Paywall →