Beginner Personalization

This guide will walk you through how to make a custom personalization API and integrate it with your application. It will switch text or an image based on the referrer (e.g. an email campaign or an ad), but you can also hide/show content, change a workflow, and much more.

Time: About an hour Level: Beginner

To get a free sandbox account, sign up here.

2. Instrument your site or application (no code)

You can send event data to Sumatra using Google Tag Manager, adding Sumatra as a destination in Segment or Rudderstack, or use one of the SDKs. The remainder of this guide will assume you are using Google Tag Manager.

In your Tag Manager account, navigate to Templates, click "Search Gallery", and type "Sumatra", and select "Sumatra Integration". This will add a Tag Template that will send pageviews and click events to Sumatra.

create-workspace

Important

Be sure to add your private API key, which can be found on the Settings page of your Sumatra account.

Learn more about API integration

3. Custom orchestration layer & decision logic (included in all paid plans)

From here, the experts at Sumatra will prepare custom data schema and low-code logic for decisions that trigger actions in your product (e.g. personalization, recommendations, and fraud prevention). Once the orchestration layer is ready, you'll have a production-ready API, full visibility into the code, and self-service access to the console.

If you want to set up the orchestration layer and decision logic yourself, complete Steps 3.a. and 3.b.

a. Define your events in Sumatra (optional self-service)

Sumatra interprets JSON events with schema that can adapt to almost any data structure, allowing you to use Sumatra with any website builder, framework, or architecture. Copy-paste the schema below into the Sumatra Editor to get started.

--- Pageview events
event page
language := $.context.device.language as string
user_agent := $.context.device.user_agent as string
path := $.context.page.path as string
referrer := $.context.page.referrer as string
search := $.context.page.search as string
title := $.context.page.title as string
url := $.context.page.url as string
session_id := $.context.session_id as string
user_id := $.context.user_id as string

-- The event that triggers the personalization
event personalize
session_id := $.context.session_id as string
user_id := $.context.user_id as string

b. Create your first 'decision' in Sumatra with low code (optional self-service)

A decision is what the API returns to trigger an action in your application. Start with one of these templates to switch text or an image for visitors arriving from specified referrers. In the example, the referrers are instagram and youtube, but you can use referrers from your sales emails, ads, or anything else.

Switch text

-- Personalize text for users from instagram and youtube
event personalize
first_referrer := First<page>(referrer by user_id)
heading := Case(
     when first_referrer.Contains("instagram.com") then "Join 1,000+ influencers like you"
     when first_referrer.Contains("youtube.com") then "Join 1,000+ artists like you"
     default "Join 1,000+ creators like you"
)

Switch image

-- Personalize an image for users from instagram and youtube
event personalize
first_referrer := First<page>(referrer by user_id)
hero := Case(
     when first_referrer.Contains("instagram.com") then "/assets/instagram.png"
     when first_referrer.Contains("youtube.com") then "/assets/youtube.png"
     default "/assets/creator.png"
)

After adding the template, click "Publish" and confirm the changes on the "Apply" screen.

Learn about low-code development

4. Trigger the 'decision' from your application

Add the snippet to the copy or image you want to personalize.

window.sumatra.enrich('personalize').then((enriched) => {
    // set heading to enriched.features.heading
    // OR set image to enriched.features.hero
});

With this added, when a user arrives from the specified URL, they will see the alternate text or image. The enrich snippets calls the API and returns a decision.

Next steps

Congratulations! You added personalization to your application. You have self-service access to edit the low-code decision logic as often as you need without changing the API integration.

Case Study: The Zebra
Intermediate personalization with behavioral segmentation (coming soon!)
Advanced personalization with custom ML models (coming soon!)