aa-conversion-funnel-analysis

What this skill does

# Conversion Funnel Analysis (Adobe Analytics)

Analyze a multi-step conversion funnel to identify where visitors drop off,
which steps have the worst leakage, and what drives visitors to convert or
abandon. Uses AA visit-level segment-based reporting to simulate funnel steps.

> **AA Container Model:** AA funnels use **hit**, **visit**, and **visitor**
> containers — not CJA's event/session/person. Funnel steps are defined as
> visit-level segments (visitors who completed the step during a visit).
>
> **Reporting approach:** AA does not have a native sequential fallout API
> accessible via MCP. This skill approximates fallout by creating or finding
> visit-level segments for each funnel step, then running the metric for
> each step segment to compute pass-through rates.

---

## AA MCP Tools Used

- `findReportSuites` — select report suite
- `setSessionDefaults` — set session context (reportSuiteId + globalCompanyId)
- `findDimensions` — discover page/event dimensions for step definition
- `findMetrics` — find visits or orders as the counting metric
- `searchDimensionItems` — validate page names or event values
- `findSegments` — find existing step segments if available
- `upsertSegment` — create visit-level step segments if not found
- `runReport` — run visits count for each step segment

---

## Phase 0 — Setup

1. Confirm report suite with `findReportSuites` / `setSessionDefaults`.
2. Ask the user about the overall funnel scope (visit or visitor level):
   - **Visit-level funnel:** all steps happen within a single visit
     (typical for checkout funnels)
   - **Visitor-level funnel:** steps can span multiple visits
     (typical for lifecycle funnels)

```
findReportSuites(globalCompanyId: "<gcid>", page: 0, limit: 10)
setSessionDefaults(globalCompanyId: "<gcid>", reportSuiteId: "<rsid>")
```

---

## Phase 1 — Define the Funnel Steps

Ask the user to describe each step of the funnel in plain language.
Prompt for 3–8 steps. Example:

1. Product page viewed
2. Add to cart
3. Checkout started
4. Payment info entered
5. Order confirmed (purchase)

For each step, ask:
- "Is this defined by a page view (page name or URL), a custom event, or
  a combination?"
- "Should this step be at the **hit** level (single page/event) or
  **visit** level (any visit where this happened)?"

---

## Phase 2 — Discover Components

### 2.1 Validate page names

For page-based steps:

```
findDimensions(page: 1, limit: 500)   # returns all available dimensions; look for variables/page
searchDimensionItems(
  dimensionId: "variables/page",
  searchOr: "<step page keywords>",   # space-separated keywords OR'd together
  startDate: "<start>",
  endDate: "<end>",
  page: 1,
  limit: 20
)
```

Common page dimension IDs: `variables/page`, `variables/entrypage`, `variables/exitpage`.
Confirm the correct page name value with the user if multiple matches exist.

> **Note:** `searchDimensionItems` uses `searchOr` or `searchAnd` for filtering — not `searchTerm`.
> If no rows return, try a wider date range — some report suites only have historical data.

### 2.2 Validate events/metrics

For event-based steps (add to cart, checkout, purchase):

```
findMetrics(expansions: "componentType,categories", page: 0, limit: 200)
# Filter results locally by name: visits, orders, pageviews, etc.
```

---

## Phase 3 — Find or Create Step Segments

For each funnel step, search for an existing segment:

```
findSegments(searchTerm: "<step description>")
```

If an appropriate visit-level segment exists, use it directly.

If not, create a new visit-level segment for each step:

```
upsertSegment(
  definition: {
    "name": "Visit: Checkout Started",
    "description": "Visits where the visitor reached the checkout page",
    "reportSuiteID": "<rsid>",
    "container": {
      "func": "segment",
      "context": "visits",
      "pred": {
        "func": "streq",
        "val": "/checkout",
        "str": "/checkout",
        "dimension": "variables/page"
      }
    },
    "tags": [{ "name": "funnel" }]
  }
)
```

Create all step segments before running reports. Record each segment `id`.

> **Important:** Only create new segments with explicit user confirmation.
> Present the list of segments to be created and ask: "I need to create N
> visit-level segments to define your funnel steps. Is that OK?"

---

## Phase 4 — Run Funnel Step Reports

For each step segment, run the visits count over the analysis period:

```
runReport(
  dimensionId: "variables/page",    # required by AA runReport
  metricIds: "metrics/visits",      # note: plural field name "metricIds"
  segmentIds: "<step segment id>",  # note: plural field name "segmentIds"
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# summaryData.totals[0] is the total visits for this segment
```

This is 1 call per funnel step. For a 5-step funnel = 5 calls.

Also run total visits (no segment) as the 100% baseline:

```
runReport(
  dimensionId: "variables/page",
  metricIds: "metrics/visits",
  startDate: "<start>",
  endDate: "<end>",
  limit: 1
)
# Use summaryData.totals[0] as the baseline visit count
```

> **AA runReport field names:** Use `metricIds` (not `metricId`) and `segmentIds` (not `segmentId`).
> Use `startDate`/`endDate` (ISO 8601) rather than a `dateRange` object.
> Always read totals from `summaryData.totals[0]`, not from `rows`.

---

## Phase 5 — Compute Funnel Metrics

For each step, compute:

| Metric | Formula |
|---|---|
| Step visits | Raw count from `runReport` |
| Step conversion rate | Step visits / Total visits × 100 |
| Step-to-step rate | Step N visits / Step N-1 visits × 100 |
| Step-to-step drop-off | Step N-1 visits - Step N visits |
| Drop-off rate | 100 - step-to-step rate |

Identify the **biggest leakage step** (highest absolute drop-off count) and
the **weakest conversion step** (lowest step-to-step rate).

---

## Phase 6 — Drill Into the Worst Step

For the step with the highest drop-off, run a dimension breakdown to find
what differentiates visitors who progressed vs. those who dropped:

```
runReport(
  dimensionId: "variables/mobiledevicetype",
  metricIds: "metrics/visits",
  segmentIds: "<worst step segment>",
  startDate: "<start>",
  endDate: "<end>",
  limit: 10
)

runReport(
  dimensionId: "variables/mobiledevicetype",
  metricIds: "metrics/visits",
  segmentIds: "<next step segment>",
  startDate: "<start>",
  endDate: "<end>",
  limit: 10
)
```

Compare the device-type mix between visitors who completed the worst step
and those who made it to the next step. Repeat for 1–2 other dimensions
(e.g., traffic source, new vs. returning).

---

## Phase 7 — Generate HTML Report

Build the funnel report inline and write to
`/tmp/aa_funnel_analysis_report_<YYYY-MM-DD_HHMMSS>.html`.


### HTML template

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Funnel Health &mdash; {ORG_NAME} &mdash; {FUNNEL_NAME}</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700;900&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
  * { box-sizing: border-box; margin: 0; padding: 0; }
  :root {
    --bg: #f5f4f1;
    --surface: #ffffff;
    --ink: #1a1a1a;
    --ink-muted: #6b6b6b;
    --border: #e5e2dc;
    --header-bg: #0e0e10;
    --header-warm: #3a1010;
    --accent-red: #c8312f;
    --accent-red-bright: #ff6b68;
    --accent-red-soft: #fdecea;
    --accent-green: #1f7a4d;
    --accent-yellow: #d4a017;
  }
  body { font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
         background: var(--bg); color: var(--ink); line-height: 1.5;
         -webkit-font-smoothing: antialiased; }

  /* === Header === */
  header { background: linear-gradient(120deg, var(--header-bg) 0%, #1a0d0d 55%, var(--header-warm) 100%);
           color: #fff; padding: 56px 56px 44px; position: relat