Quickstart

Overview

Client-Side vs. Server-Side Integration

This guide explains how to perform a client-side integration in three easy steps.

For server-side integration, where session verification is done on the backend before delivering content, you will need to complete 'Quickstart' first, followed by two additional steps.

The first 3-Steps

Integrating tiun is straightforward. We will guide you through the three steps where you learn how to:

1

Create the snippet

Configure the look and feel of your payment snippet

2

Embed the snippet code in your website

Add the snippet code to your webpage

3

Handle all events

Receive and send snippet events

In case you have questions, feel free to reach out to [email protected]

---

Let's get to work

Log in

Please log into your tiun.business account here or visit our website at tiun.io

After logging in, you'll be directed to your home screen, the dashboard.

Navigate to 'Connect and Pay'

Find the 'Connect and Pay' product in our side navigation on the left.

In the side navigation you see 'Connect and Pay / Configuration' selected.

Let's continue

1

Create the snippet

Configure the look and feel of your payment snippet.

Go to section 'Design' where you can configure our snippet:

All changes can be previewed in real-time below for both parts - the 'Paywall Snippet' and 'Background Snippet.'

In this section, you can customize the design of the snippet 'Connect and Pay / Configuration / Design'.

Our payment snippet consists of two parts.

It's important to understand that the integration of both parts in your web app are essential for the payment to work.

Part 1: Paywall (Paywall snippet)

This payment element is the equivalent of a checkout (UI component) that you can integrate into your paywall. Please note that we only supply the snippet itself and not the full paywall. Designing the paywall is your responsibility.

Part 2: Badge (Background snippet)

This script operates in the background to track user sessions, ensuring precise billing. We comply with GDPR regulations, so we only set cookies if the user interacts with the paywall snippet.

Copy the snippet code

Below the preview you can copy the snippet code for the 'Paywall Snippet' and the 'Background Snippet'

View option to 'Copy' out both snippet codes

2

Embed the snippet code in your website

Add the snippet code to your webpage.

Adding the background snippet

To ensure consistent script loading throughout the application, paste the two code snippets (JavaScript and CSS) that you copied in the last step into your index.html file's header. This placement is necessary for the snippet's session tracking functions, like pausing on non-paid content, to work correctly.

<script src="https://api-staging.tiun.live/live_api/v1/snippets/<your-snippet-id>/background_js?appearance=light&language=de"></script>
<link rel="stylesheet" href="https://api-staging.tiun.live/live_api/v1/snippets/<your-snippet-id>/background_css" />

Adding the paywall snippet

On your paywall, paste the DIV in the place where the tiun payment snippet should be loaded and displayed.

<div id="tiunPaymentSnippet" />

3

Handle all events

Receive and send snippet events

What's important to understand

Most systems you've used probably employ an 'Auth Token' for user authentication verification and an 'Entitlement Engine' to assess access rights, like confirming an active subscription.

At tiun, we implement a concept known as Session Management. Unlike authentication tokens, which may remain valid for up to 10 days, sessions are governed by shorter, variable time intervals. It’s crucial to note that our primary metric is time, which continuously adapts. Users transition through various stages: Locked → Active → Paused → Ended.

How sessions work

Users unlock your content by starting sessions. As session states change, the events TIUN_HIDE_PAYWALL and TIUN_SHOW_PAYWALL are triggered. Each user session transitions through the states shown in the diagram below. Once a session concludes, a new one is automatically initiated.

Handling the paywall events

Start with showPaywall=true and connect the tiun events with your paywall logic, as shown in this example:

window.addEventListener('message', (event) => {
	if (event.data?.type === 'TIUN_EVENT') {
		if (event.data?.content === 'TIUN_HIDE_PAYWALL') {
			// TODO: add your logic to hide the paywall

		} else if (event.data?.content === 'TIUN_SHOW_PAYWALL') {
			// TODO: add your logic to show the paywall

		}
	}
});

Indicating paid and free content

You can listen to the TIUN_SNIPPET_INITIALIZED event that is fired when the snippet is initialized.

Assuming you have free or paid content, the snippet session should be active for the paid content and inactive for the free content.

To let the background snippet know when to pause or activate the session, you can use the TIUN_UPDATE_CONTENT event and the contentType property.

window.addEventListener('message', (event) => {
  if (event.data?.type === 'TIUN_EVENT') {
    if (event.data?.content === 'TIUN_SNIPPET_INITIALIZED') {
      updateContentInfo();
    }
    // other event handlers go here
  }
});

function updateContentInfo() {
  var isPaidContent = ... // add your condition(s) here

  window.postMessage(
    {
      type: 'TIUN_EVENT',
      content: 'TIUN_UPDATE_CONTENT',
      contentId: 'content ID', // optional (see description below)
      contentType: isPaidContent ? 'active' : 'inactive'
    },
    window.location.origin
  );
}

Then, on each route change or page load, call the method again to let the snippet know if the new content is paid or free:

updateContentInfo();

Configuring the contentId property (optional)

The contentId property is an optional setting within the TIUN_UPDATE_CONTENT event. This property represents the identifier of a specific content item, typically originating from your Content Management System (CMS). Setting contentId enables enhanced analytics on your tiun business dashboard, such as detailed breakdowns of reading time per content item. If contentId is not explicitly set (i.e., left null), the system defaults to using the URL route as the identifier.

That's a wrap!

Next up (optional)

For server-side integration, where session verification happens on the backend before content delivery, you must complete the 'Advanced Session Verification' by following these two additional steps.