Implement Adobe Analytics via Web SDK (AEP SDK) — Complete Guide

The AEP Web SDK — also known as alloy.js — is Adobe's modern implementation method for the entire Experience Cloud. One tag, one network request, multiple Adobe products. If you are still running AppMeasurement, you are running on infrastructure that Adobe has effectively deprecated for new implementations.

I have led several AppMeasurement to Web SDK migrations at enterprise scale. This guide covers the full implementation — from datastream setup to XDM schema design to Adobe Launch configuration — along with the migration considerations that most guides skip.

Why Web SDK? The case for migrating

The business case for migrating to the AEP Web SDK is not just about keeping up with Adobe's roadmap. There are concrete technical advantages:

How the Web SDK architecture works

Understanding the architecture before touching any configuration prevents a category of mistakes that are very expensive to fix later.

Understanding XDM and its role in Analytics

XDM — Experience Data Model — is a standardized JSON schema system that defines how data is structured when sent through the Web SDK. Instead of assigning values directly to eVar1 or prop5, you send structured objects that map to predefined field groups.

Adobe Analytics still uses eVars and props internally. The translation happens in two ways:

• Automatic mapping — certain XDM fields (like web.webPageDetails.name) automatically populate standard Analytics dimensions (Page Name)
• Manual mapping — custom XDM fields in the _experience.analytics namespace map directly to specific eVars and props, configured in the Analytics report suite settings

Prerequisites before implementation

• An AEP sandbox (production or development) with Data Collection permissions
• An Adobe Analytics report suite — separate ones for development and production
• Adobe Launch property with appropriate permissions
• A defined XDM schema — do not start implementation without this
• A measurement plan mapping your business KPIs to XDM fields and Analytics variables

Step 1 — Configure your Datastream

The Datastream is the server-side configuration that tells the Edge Network where to route your data. Think of it as the routing table for your Web SDK implementation.

Step 2 — Design your XDM schema

In AEP, navigate to Schemas → Create Schema → XDM ExperienceEvent. This is the schema type for web behavioral data. Add the following field groups as a starting point:

• AEP Web SDK ExperienceEvent — required, adds web interaction fields
• Web Details — page URL, referrer, page name
• Environment Details — browser, device, operating system
• Adobe Analytics ExperienceEvent Full Extension — adds the _experience.analytics namespace for direct eVar/prop mapping

{
  xdm: {
    // Standard web fields — auto-mapped to Analytics
    web: {
      webPageDetails: {
        name: "Home:Hero",         // → Page Name
        URL: window.location.href,
        isHomePage: true
      },
      webReferrer: {
        URL: document.referrer
      }
    },
    // Custom Analytics variables via _experience namespace
    _experience: {
      analytics: {
        customDimensions: {
          eVars: {
            eVar1: "Home:Hero",      // Page Name
            eVar2: "homepage",        // Page Type
            eVar3: "marketing",       // Page Section
            eVar10: "logged-out"     // Login Status
          },
          props: {
            prop1: "Home:Hero"
          }
        },
        event1to100: {
          event1: { value: 1 }     // Page View event
        }
      }
    }
  }
}

Step 3 — Install the Web SDK extension in Adobe Launch

In your Launch property, go to Extensions → Catalog → search for "Adobe Experience Platform Web SDK". Install it and configure:

• Instance name: alloy (keep the default unless you have a specific reason to change it)
• Datastream ID: paste the ID from Step 1. Set up environment overrides for dev, staging, and production using their respective Datastream IDs
• Identity namespace: configure ECID handling here — leave defaults unless you are implementing a custom identity strategy
• Privacy: configure consent defaults — "in" for all, "pending" if you have a consent management platform, or "out" if you are in a strict consent regime

Step 4 — Create XDM data elements

In Launch, create a data element of type "XDM Object". This is where you build the XDM payload that will be sent with each event.

Name:   XDM - Page View
Type:   XDM Object
Schema: [your XDM schema]

// Map each field to a data element or value:
web.webPageDetails.name      = %DL - Page Name%
web.webPageDetails.URL       = %Page URL%   (built-in variable)

_experience.analytics
  .customDimensions.eVars
  .eVar1                     = %DL - Page Name%
  .eVar2                     = %DL - Page Type%
  .eVar3                     = %DL - Page Section%
  .eVar10                    = %DL - Login Status%

Step 5 — Create page view and event rules

The Web SDK uses

sendEvent

s.t()

s.tl()

Your page load rule in Launch:

Name:    Page Load — Send Web SDK Event
Event:   Core → Library Loaded (Page Top)
Order:   50

Actions:
  1. Adobe Experience Platform Web SDK → Send Event
     Type:       web.webpagedetails.pageViews
     XDM Data:   %XDM - Page View%

An interaction tracking rule:

Name:    Click — CTA Button
Event:   Core → Click
         Element: .btn-primary
Order:   50

Actions:
  1. Adobe Experience Platform Web SDK → Send Event
     Type:       web.webInteraction.linkClicks
     XDM Data:   %XDM - CTA Click%

Migrating from AppMeasurement — what to know

If you are migrating an existing AppMeasurement implementation rather than starting fresh, the migration requires careful planning. The most important principle: run both implementations in parallel before cutting over.

Validation and debugging

Use these tools to validate your Web SDK implementation before promoting to production:

• AEP Debugger Chrome extension — inspect every sendEvent call, view the XDM payload, and see the Edge Network response in real time
• Network tab (Chrome DevTools) — filter by "adobedc.net" to see raw Edge Network requests and responses
• Adobe Analytics DebugView — validates that events are reaching your report suite with correct variable values
• AEP Assurance (Griffon) — enterprise-grade debugging tool that captures every SDK event in a session for detailed inspection

Common mistakes

• Publishing XDM schema changes without versioning. Breaking changes to a schema affect all consumers. Always create a new schema version for breaking changes.
• Using the same Datastream across environments. Development events will appear in your production Analytics reports. Always use environment-specific Datastreams.
• Skipping the parallel tracking period. Every migration I have seen that skipped parallel tracking had metric discrepancies discovered after the cutover — when they were much harder to explain and fix.
• Not accounting for FPID changes. The visitor count methodology change is the most common surprise in Web SDK migrations. Always brief stakeholders before cutover.
• Mixing Web SDK and AppMeasurement on the same page. Both SDKs will fire, sending duplicate data. Remove AppMeasurement completely once Web SDK is validated.