--- name: aa-conversion-funnel-analysis description: > Analyzes a multi-step conversion funnel to find where visitors drop off and which steps have the worst leakage. Use this skill when someone describes a journey and asks about conversion rates, drop-off, fallout, or step completion. Trigger for "analyze our checkout funnel," "where are visitors dropping off," "what's our add-to-cart to purchase conversion rate," "funnel analysis," "show me fallout between steps," or "which step loses the most visitors." license: Apache-2.0 metadata: author: Adobe version: "1.0" --- # 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: "", page: 0, limit: 10) setSessionDefaults(globalCompanyId: "", reportSuiteId: "") ``` --- ## 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: "", # space-separated keywords OR'd together startDate: "", endDate: "", 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: "") ``` 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": "", "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: "", # note: plural field name "segmentIds" startDate: "", endDate: "", 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: "", endDate: "", 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: "", startDate: "", endDate: "", limit: 10 ) runReport( dimensionId: "variables/mobiledevicetype", metricIds: "metrics/visits", segmentIds: "", startDate: "", endDate: "", 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_.html`. ### HTML template ```html Funnel Health — {ORG_NAME} — {FUNNEL_NAME}

Funnel Health Report

{ORG_NAME} Funnel Health

Step-by-step pass-through for the {FUNNEL_NAME} funnel during {DATE_RANGE}.

📅 {DATE_RANGE} 📊 {REPORT_SUITE} 🕔 Prepared {GENERATED_DATE}

Funnel Pass-Through

Step Detail

▾

Step	Visits	% of Total	Step Rate	Drop-off

Leakage Analysis (Worst Step: {WORST_STEP_NAME})

▾

{LEAKAGE_INSIGHT_TEXT}

Dimension	Entered Step	Completed Step	Step Rate	vs. Average

Recommendations

▾

``` **Section titles — no phase prefix**: Section headings in the HTML report must **not** include the phase number. Use the plain section name only (e.g., "Funnel Overview" not "Phase 2 — Funnel Overview", "Drop-off Analysis" not "Phase 3 — Drop-off Analysis"). Write to `/tmp/aa_funnel_analysis_report_.html` and open: ```bash open /tmp/aa_funnel_analysis_report_.html ``` --- ## Guardrails - Always present the list of segments to be created (step 3) and get user confirmation before calling `upsertSegment`. - If the user already has named segments for funnel steps, prefer using those rather than creating new ones — check `findSegments` first. - Limit funnel to 8 steps maximum for practical API call budgets. - Funnel conversion rates using visit segments are approximations — they count visits that touched each step, not strict sequential fallout. Note this limitation to the user. --- ## Example Interaction > "Analyze our checkout funnel — I want to see where visitors drop off." 1. Confirm report suite and date range (last 30 days). 2. Define 5 steps: Product View → Add to Cart → Checkout → Payment → Purchase. 3. Validate page names with `searchDimensionItems`. 4. Find existing step segments or create new ones (with user approval). 5. Run 6 reports (5 steps + total). 6. Compute: 100% → 42% (add to cart) → 28% (checkout) → 19% (payment) → 11% (purchase). Overall conversion: 11%. 7. Worst step: Add-to-Cart to Checkout (33% drop-off rate). 8. Drill in: Mobile users have only 18% checkout rate vs. 31% on Desktop. 9. Generate and open HTML report. 10. Key insight: "Mobile is your funnel's biggest liability. Consider simplifying the mobile checkout experience."