SDK Documentation

Complete guide to installing and using EmoraTest on your website.

Quick Start

Your unique SDK key — copy this to get started tracking behavioral states.

Loading...

Getting Started

EmoraTest detects user behavioral states from behavior patterns and helps you optimize conversions. Add one script to your site to start tracking sessions, emotions, and run A/B tests.

What you'll need:

• Your SDK Key — found in Settings → SDK after signing up
• Access to edit your website's HTML, JavaScript, or build configuration

Installation

Choose your platform below. The SDK loads from our CDN and initializes automatically.

HTML (Any Website)

Add this before the closing </body> tag:

html

<script src="https://emoratest.com/static/sdk/emoratest.umd.js"></script>
<script>
  EmoraTest.init({ sdkKey: "YOUR_SDK_KEY" });
</script>

React / Next.js

Create a client component and add it to your root layout:

jsx

"use client";
import { useEffect } from "react";

export default function EmoraTracker() {
  useEffect(() => {
    const script = document.createElement("script");
    script.src = "https://emoratest.com/static/sdk/emoratest.umd.js";
    script.async = true;
    script.onload = () => {
      window.EmoraTest?.init({ sdkKey: "YOUR_SDK_KEY" });
    };
    document.body.appendChild(script);
  }, []);
  return null;
}

// Then add <EmoraTracker /> to your root layout.

Vue.js

Use the onMounted hook in your setup script:

vue

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');
  script.src = 'https://emoratest.com/static/sdk/emoratest.umd.js';
  script.async = true;
  script.onload = () => {
    window.EmoraTest?.init({ sdkKey: 'YOUR_SDK_KEY' });
  };
  document.body.appendChild(script);
});
</script>

Shopify

Go to Online Store → Themes → Edit code, open theme.liquid, and paste before the closing </body> tag:

html

<script src="https://emoratest.com/static/sdk/emoratest.umd.js"></script>
<script>
  EmoraTest.init({ sdkKey: "YOUR_SDK_KEY" });
</script>

WordPress

Option A: Use the "WPCode" plugin. Go to Code Snippets → Add New, paste the HTML snippet, and set location to "Site Wide Footer".

Option B: Add to your theme's functions.php:

php

function emoratest_tracking() { ?>
  <script src="https://emoratest.com/static/sdk/emoratest.umd.js"></script>
  <script>EmoraTest.init({ sdkKey: "YOUR_SDK_KEY" });</script>
<?php }
add_action('wp_footer', 'emoratest_tracking');

Google Tag Manager

Go to Tags → New → Custom HTML, paste the snippet, set trigger to "All Pages", then publish:

html

<script src="https://emoratest.com/static/sdk/emoratest.umd.js"></script>
<script>
  EmoraTest.init({ sdkKey: "YOUR_SDK_KEY" });
</script>

NPM Package

Coming soon — use the script tag method for now.

Important: Replace YOUR_SDK_KEY with the key from Settings → SDK.

The SDK automatically handles session persistence across pages — no additional code needed.

What Gets Tracked Automatically

Once installed, the SDK automatically tracks all user behavior signals:

🖱️

Mouse movements

Every cursor movement tracked for behavioral analysis

👆

Clicks

All clicks with element targets and timestamps

📜

Scroll behavior

Scroll depth, velocity, and patterns

😤

Rage clicks

Rapid clicking indicates frustration

🚪

Exit intent

Cursor moving toward close button

↕️

Scroll retreats

Back-and-forth scrolling shows confusion

⏱️

Session duration

Time spent on each page

📄

Page URLs

Navigation tracking across pages

No extra code needed! Just install and the dashboard will start showing session data, behavioral state predictions, and behavior signals within seconds.

Tracking Conversions & Outcomes

Use reportOutcome() to mark session outcomes. This tells EmoraTest the final result of a user's journey.

Available outcome types:

purchase — Completed purchase
signup — Signed up / registered
checkout_completed — Finished checkout
demo_booked — Scheduled a demo
lead_generated — Submitted lead form
trial_started — Started free trial

Manual Outcome Reporting

javascript

// Example 1: After successful purchase
function onPurchaseComplete() {
  // Your order logic
  completeOrder();

  // Report outcome to EmoraTest
  if (window.EmoraTest) {
    window.EmoraTest.reportOutcome('purchase');
  }
}

// Example 2: After signup form submission
document.getElementById('signup-form').addEventListener('submit', function() {
  // Your signup logic
  submitSignup();

  // Report outcome
  if (window.EmoraTest) {
    window.EmoraTest.reportOutcome('signup');
  }
});

// Example 3: React/Next.js - after demo booking
const handleDemoBooked = async () => {
  const result = await bookDemo();

  if (result.success && window.EmoraTest) {
    window.EmoraTest.reportOutcome('demo_booked');
  }
};

// Example 4: After checkout completion
const onCheckoutComplete = () => {
  if (window.EmoraTest) {
    window.EmoraTest.reportOutcome('checkout_completed');
  }
};

Auto-Detection (Built-in)

EmoraTest automatically detects outcomes from common URL patterns:

URL Pattern	Auto Outcome
/success, /thank-you, /confirmation	`purchase`
/signup/success, /registered	`signup`
/checkout/success, /order/confirm	`checkout_completed`
/demo/booked, /meeting/scheduled	`demo_booked`

Tip: Auto-detection runs automatically after SDK init. You can also trigger manually with EmoraTest.detectOutcomeFromUrl()

Session Outcome Lifecycle

Session starts

outcome = 'unknown'

User takes action

You call reportOutcome()

Outcome saved

outcome = 'purchase' (or other)

User leaves without action

auto-set to 'abandon'

Running A/B Tests

⚠️ A/B Testing is in Beta. Feature flag evaluation works, but full experiment tracking and statistical results are still being finalized.

EmoraTest includes a full-featured A/B testing platform. Create flags, assign variants, and track which version performs better.

Step 1: Create a Feature Flag

Go to Experiments in the dashboard
Click New Experiment
Enter a key (e.g., hero-headline) and name
Add 2 variants: control (50%) and variant_b (50%)
Click Activate

Step 2: Use the Flag in Your Code

On the page you want to test, evaluate the flag and show different content:

javascript

// Wait for the SDK to evaluate the flag
async function setupABTest() {
  const result = await EmoraTest.evaluateFlag('hero-headline');

  if (result.variant === 'control') {
    // Original version
    document.getElementById('headline').textContent = 'Welcome to Our Store';
  } else if (result.variant === 'variant_b') {
    // New version to test
    document.getElementById('headline').textContent = 'Shop the Best Deals Today';
  }
}

setupABTest();

// In React/Next.js:
import { useEffect, useState } from 'react';

function Headline() {
  const [headline, setHeadline] = useState('Loading...');

  useEffect(() => {
    EmoraTest.evaluateFlag('hero-headline').then(result => {
      if (result.variant === 'control') {
        setHeadline('Welcome to Our Store');
      } else {
        setHeadline('Shop the Best Deals Today');
      }
    });
  }, []);

  return <h1>{headline}</h1>;
}

Step 3: Track Conversions

Make sure you call EmoraTest.reportOutcome('purchase') on your conversion page (see Section 4 above).

Step 4: Check Results

Go to Experiments → click on your experiment. Statistical significance reporting is being improved and will show detailed results in future updates.

How it works: Each visitor automatically gets assigned one variant and always sees the same one. The SDK handles this deterministically using stable hashing — you don't need to manage user assignments.

A/B Test Examples

Test Button Color

javascript

const result = await EmoraTest.evaluateFlag('cta-button-color');
const button = document.getElementById('cta-button');

if (result.variant === 'control') {
  // Original: Blue button
  button.style.backgroundColor = '#007BFF';
  button.textContent = 'Buy Now';
} else {
  // Variant: Orange with urgency
  button.style.backgroundColor = '#FF6B00';
  button.textContent = 'Buy Now — Free Shipping';
}

Test Entire Page Sections

javascript

const result = await EmoraTest.evaluateFlag('pricing-layout');

if (result.variant === 'control') {
  document.getElementById('pricing-v1').style.display = 'block';
  document.getElementById('pricing-v2').style.display = 'none';
} else {
  document.getElementById('pricing-v1').style.display = 'none';
  document.getElementById('pricing-v2').style.display = 'block';
}

Test with More Than 2 Variants

Create a flag with 3 variants (control 34%, variant_b 33%, variant_c 33%) and use a switch statement:

javascript

const result = await EmoraTest.evaluateFlag('hero-variant');
const hero = document.getElementById('hero');

switch (result.variant) {
  case 'control':
    hero.innerHTML = '<h1>Start your free trial</h1><p>No credit card required</p>';
    break;
  case 'variant_b':
    hero.innerHTML = '<h1>Get started today</h1><p>14-day free trial</p>';
    break;
  case 'variant_c':
    hero.innerHTML = '<h1>Free Shipping Today</h1><p>Use code: FREESHIP</p>';
    break;
}

Understanding Your Dashboard

The EmoraTest dashboard gives you deep insights into user behavior and behavioral states.

📊

Overview

Your command center. See session counts, dominant behavioral states, friction scores, and abandonment risks all at a glance.

📊

Sessions

Every user visit. Shows behavioral state detected (frustrated, confused, engaged, disengaged), friction score, and outcome. Real-time updates.

📊

Page Insights

See which pages cause the most emotional friction. Session counts, dominant behavioral state, average duration, and behavioral signals for each page.

📊

Diagnosis

Automatically detects UX issues like rage click clusters, high bounce rates, scroll confusion, form abandonment, and hesitation patterns. Each issue includes severity and specific recommendations.

📊

Experiments

Your A/B tests. Create experiments, assign variants, track which version performs better. Currently in beta — statistical reporting is being improved.

📊

Alerts

Set up alerts to get notified when emotional friction spikes on any page. Configure rules like 'Alert me when frustration exceeds 30% on /checkout.' Notifications via email or Slack webhook.

📊

Emotion Analysis

Each session gets a behavioral state prediction (frustrated, confused, engaged, disengaged) based on mouse behavior patterns. Predictions are made after the session ends or sufficient data is collected.

SDK Reference

Complete reference of all available EmoraTest SDK methods.

Method	Description
`await EmoraTest.init({ sdkKey, apiUrl })`	Initialize the SDK. Call once per page load. apiUrl is optional — defaults to the domain serving the SDK script.
`await EmoraTest.reportOutcome(outcome)`	Report session outcome. Options: purchase, signup, checkout_completed, demo_booked, lead_generated, trial_started, abandon.
`EmoraTest.detectOutcomeFromUrl()`	Auto-detect outcome from URL patterns. Runs automatically on init, or call manually.
`await EmoraTest.evaluateFlag(flagKey)`	Get assigned variant for an A/B test. Returns { assigned: boolean, variant: string \| null }.
`await EmoraTest.getVariant(flagKey)`	Convenience method that returns just the variant string or null.
`EmoraTest.getSessionId()`	Get the current session ID (changes on each page visit).
`EmoraTest.isInitialized()`	Check if the SDK has been initialized and is actively tracking.
`EmoraTest.isLimitReached()`	Check if the monthly session limit has been reached.
`await EmoraTest.destroy()`	Clean up the SDK instance, flush events, and end session. Useful for single-page apps.

Troubleshooting

Common issues and how to fix them.

SDK not loading / window.EmoraTest is undefined

Check that the script src URL is correct. Open browser DevTools Console to see error messages. For Next.js, make sure your component has 'use client' directive.

401 Unauthorized errors in console

Your SDK key is invalid. Go to Settings → SDK in the dashboard and copy the current key. Make sure you didn't accidentally include extra spaces.

Sessions not appearing in dashboard

Verify the SDK is loaded by typing window.EmoraTest in the browser console. If using localhost, ensure your backend is running.

A/B test always shows the same variant

This is correct! Each visitor always gets the same variant for consistency. Open an incognito window to see the other variant. The SDK uses stable hashing based on visitor ID.

Session shows 'Not enough data'

Sessions shorter than 10 seconds or with fewer than 5 events will show 'Not enough data' instead of a behavioral prediction. This is by design — very short sessions don't have enough behavioral data for a reliable prediction.

Content Security Policy (CSP) errors

Add your EmoraTest instance URL to your CSP script-src directive. For Next.js, update next.config.js headers() to include your instance URL in script-src.

Questions? Email [email protected]