Heatmap-Informed Creative Optimization

Scenario

Wistia’s engagement heatmap shows per-second viewer retention for every video — the exact moments where viewers rewatch, skip, or drop off. This job pulls the engagement data for a video, identifies the sharpest drop-off points, then sends the timestamp and context to Mave with the question: “Viewers drop off at 0:45. Research best practices. Suggest specific edits.” The result is a creative revision plan grounded in actual viewer behavior — not gut instinct — with research-backed recommendations for each drop-off moment.

Architecture

Code

import os, requests, time

WS = os.environ["WISTIA_API_TOKEN"]
MV = os.environ["MAVERA_API_KEY"]
WS_BASE = "https://api.wistia.com"
MV_BASE = "https://app.mavera.io/api/v1"
WS_H = {"Authorization": f"Bearer {WS}", "Accept": "application/json"}
MV_H = {"Authorization": f"Bearer {MV}", "Content-Type": "application/json"}

MEDIA_HASHED_ID = "abc123def4"

# 1. Fetch media stats with engagement data
media_stats = requests.get(
    f"{WS_BASE}/v1/stats/medias/{MEDIA_HASHED_ID}.json", headers=WS_H
).json()

media_name = media_stats.get("name", MEDIA_HASHED_ID)
duration = media_stats.get("duration", 0)
play_count = media_stats.get("play_count", 0)
engagement = media_stats.get("engagement", 0)

print(f"Video: \"{media_name}\" | Duration: {duration:.0f}s | Plays: {play_count} | Engagement: {engagement:.1%}")

# 2. Get engagement graph (per-second retention)
engagement_data = media_stats.get("engagement_data", [])
if not engagement_data:
    medias_resp = requests.get(
        f"{WS_BASE}/v1/stats/medias/{MEDIA_HASHED_ID}/engagement.json", headers=WS_H
    ).json()
    engagement_data = medias_resp if isinstance(medias_resp, list) else []

# 3. Identify drop-off points (where retention drops >10% within 5 seconds)
drop_offs = []
for i in range(5, len(engagement_data)):
    current = engagement_data[i]
    previous = engagement_data[i - 5]
    drop = previous - current
    if drop > 0.10:
        timestamp_sec = i
        mins = timestamp_sec // 60
        secs = timestamp_sec % 60
        drop_offs.append({
            "timestamp": f"{mins}:{secs:02d}",
            "seconds": timestamp_sec,
            "retention_before": round(previous * 100, 1),
            "retention_after": round(current * 100, 1),
            "drop_pct": round(drop * 100, 1),
        })

# Deduplicate nearby drops (keep the steepest within 10-second windows)
filtered_drops = []
for d in sorted(drop_offs, key=lambda x: -x["drop_pct"]):
    if not any(abs(d["seconds"] - f["seconds"]) < 10 for f in filtered_drops):
        filtered_drops.append(d)

filtered_drops.sort(key=lambda x: x["seconds"])
print(f"\nIdentified {len(filtered_drops)} significant drop-off points:")
for d in filtered_drops:
    print(f"  {d['timestamp']} — Retention: {d['retention_before']}% → {d['retention_after']}% (−{d['drop_pct']}%)")

# 4. Send to Mave for creative optimization recommendations
drop_block = "\n".join(
    f"- At {d['timestamp']}: retention drops from {d['retention_before']}% to "
    f"{d['retention_after']}% (−{d['drop_pct']}% in 5 seconds)"
    for d in filtered_drops
)

# 5. Build retention curve summary
curve_points = []
for pct in [0, 10, 25, 50, 75, 90, 100]:
    idx = int(len(engagement_data) * pct / 100)
    if idx < len(engagement_data):
        curve_points.append(f"  {pct}% through: {engagement_data[idx]*100:.1f}% still watching")

optimization = requests.post(f"{MV_BASE}/mave/chat", headers=MV_H, json={
    "message": f"""Analyze these video drop-off points and suggest specific creative edits.

VIDEO: "{media_name}" ({duration:.0f}s, {play_count:,} plays)
OVERALL ENGAGEMENT: {engagement:.1%}

RETENTION CURVE:
{chr(10).join(curve_points)}

DROP-OFF POINTS:
{drop_block}

For each drop-off point:
1. **Likely Cause**: What typically causes viewers to leave at this point in a video? Research best practices.
2. **Specific Edit**: Describe exactly what to change at this timestamp (cut, restructure, add element, change pacing)
3. **Before/After**: Write the transition from what's probably happening now to what should happen instead
4. **Expected Impact**: Estimate retention improvement if this edit is made

Also provide:
5. **Opening Assessment**: Is the first 5 seconds strong enough? What would improve it?
6. **Pacing Diagnosis**: Is the video front-loaded, back-loaded, or evenly paced?
7. **Optimal Length**: Based on the retention curve, what should this video's runtime be?""",
}).json()

print("\nHEATMAP-INFORMED CREATIVE OPTIMIZATION")
print("=" * 60)
print(f"Video: {media_name}")
print(f"Plays: {play_count:,} | Engagement: {engagement:.1%} | Drop-offs: {len(filtered_drops)}")
print("\n" + optimization.get("content", "")[:2500])

const WS = process.env.WISTIA_API_TOKEN;
const MV = process.env.MAVERA_API_KEY;
const WS_BASE = "https://api.wistia.com";
const MV_BASE = "https://app.mavera.io/api/v1";
const WS_H = { Authorization: `Bearer ${WS}`, Accept: "application/json" };
const MV_H = { Authorization: `Bearer ${MV}`, "Content-Type": "application/json" };

const MEDIA_HASHED_ID = "abc123def4";

// 1. Media stats with engagement
const mediaStats = await fetch(
  `${WS_BASE}/v1/stats/medias/${MEDIA_HASHED_ID}.json`, { headers: WS_H }
).then(r => r.json());

const mediaName = mediaStats.name || MEDIA_HASHED_ID;
const duration = mediaStats.duration || 0;
const playCount = mediaStats.play_count || 0;
const engagement = mediaStats.engagement || 0;

console.log(`Video: "${mediaName}" | ${Math.round(duration)}s | ${playCount} plays | ${(engagement * 100).toFixed(1)}%`);

// 2. Engagement data
let engagementData = mediaStats.engagement_data || [];
if (!engagementData.length) {
  const engResp = await fetch(
    `${WS_BASE}/v1/stats/medias/${MEDIA_HASHED_ID}/engagement.json`, { headers: WS_H }
  ).then(r => r.json());
  engagementData = Array.isArray(engResp) ? engResp : [];
}

// 3. Identify drops (>10% in 5-second window)
const dropOffs = [];
for (let i = 5; i < engagementData.length; i++) {
  const drop = engagementData[i - 5] - engagementData[i];
  if (drop > 0.10) {
    dropOffs.push({
      timestamp: `${Math.floor(i / 60)}:${String(i % 60).padStart(2, "0")}`,
      seconds: i,
      retentionBefore: Math.round(engagementData[i - 5] * 1000) / 10,
      retentionAfter: Math.round(engagementData[i] * 1000) / 10,
      dropPct: Math.round(drop * 1000) / 10,
    });
  }
}

// Deduplicate (keep steepest per 10s window)
const filteredDrops = [];
for (const d of dropOffs.sort((a, b) => b.dropPct - a.dropPct)) {
  if (!filteredDrops.some(f => Math.abs(d.seconds - f.seconds) < 10)) {
    filteredDrops.push(d);
  }
}
filteredDrops.sort((a, b) => a.seconds - b.seconds);

console.log(`\n${filteredDrops.length} drop-off points:`);
filteredDrops.forEach(d =>
  console.log(`  ${d.timestamp} — ${d.retentionBefore}% → ${d.retentionAfter}% (−${d.dropPct}%)`)
);

// 4. Retention curve summary
const curvePoints = [0, 10, 25, 50, 75, 90, 100].map(pct => {
  const idx = Math.floor(engagementData.length * pct / 100);
  return idx < engagementData.length
    ? `  ${pct}% through: ${(engagementData[idx] * 100).toFixed(1)}% watching`
    : "";
}).filter(Boolean).join("\n");

// 5. Creative optimization
const dropBlock = filteredDrops.map(d =>
  `- At ${d.timestamp}: ${d.retentionBefore}% → ${d.retentionAfter}% (−${d.dropPct}%)`
).join("\n");

const optimization = await fetch(`${MV_BASE}/mave/chat`, {
  method: "POST", headers: MV_H,
  body: JSON.stringify({
    message: `Analyze drop-offs and suggest edits.\n\nVIDEO: "${mediaName}" (${Math.round(duration)}s, ${playCount.toLocaleString()} plays)\nENGAGEMENT: ${(engagement * 100).toFixed(1)}%\n\nRETENTION:\n${curvePoints}\n\nDROP-OFFS:\n${dropBlock}\n\nPer drop-off:\n1. Likely cause\n2. Specific edit at this timestamp\n3. Before/after transition\n4. Expected retention improvement\n\nAlso:\n5. First-5-seconds assessment\n6. Pacing diagnosis\n7. Optimal length based on curve`,
  }),
}).then(r => r.json());

console.log("\nHEATMAP-INFORMED CREATIVE OPTIMIZATION");
console.log("=".repeat(60));
console.log((optimization.content || "").slice(0, 2500));

Example Output

Video: "Product Demo — Enterprise Dashboard" | 186s | 4,280 plays | 38.2%

3 drop-off points:
  0:45 — Retention: 72.3% → 58.1% (−14.2%)
  1:48 — Retention: 51.0% → 38.4% (−12.6%)
  2:41 — Retention: 34.2% → 22.8% (−11.4%)

HEATMAP-INFORMED CREATIVE OPTIMIZATION
============================================================

## Drop-Off Analysis

### At 0:45 (−14.2% retention)
**Likely Cause**: This is the classic "intro fatigue" point. The first 45
seconds likely contain branding, context-setting, or agenda slides. Viewers
who clicked expecting to see the product in action are leaving because
they haven't seen it yet.
**Specific Edit**: Cut the intro to 15 seconds maximum. Move the first
product screenshot or interaction to the 0:10 mark. Replace the agenda
slide with a 3-second text overlay: "Here's what you'll see in 3 minutes."
**Expected Impact**: +8-12% retention at 0:45 (from 58% to 66-70%)

### At 1:48 (−12.6% retention)
**Likely Cause**: Feature overload. At this point, the demo has likely
shown 3-4 features in rapid succession without connecting them to outcomes.
Viewers lose the thread of "why does this matter to me?"
**Specific Edit**: Insert a 10-second "so what" bridge at 1:40:
"That means your team saves 4 hours every Monday morning." Then transition
to the next feature. Pattern: Feature → Outcome → Feature → Outcome.
**Expected Impact**: +6-9% retention at 1:48

### At 2:41 (−11.4% retention)
**Likely Cause**: The video is too long for a product demo. Viewers who
made it this far have already decided whether they're interested. The
remaining 65 seconds are diminishing returns.
**Specific Edit**: End the video at 2:30 with a strong CTA. Move any
remaining features to a "Part 2" video for viewers who want depth.
**Expected Impact**: Eliminating the tail improves overall engagement
from 38% to an estimated 48-52%.

## Optimal Length
Based on the retention curve, this video should be **90-120 seconds**.
50% of viewers are gone by 1:48. Cut the runtime in half and engagement
will double.

Error Handling

Engagement data format

Wistia’s engagement data is an array of floats (0.0-1.0) representing the fraction of viewers still watching at each second. Some older videos may lack this granularity. If engagement_data is empty, the video may not have enough plays to generate a heatmap (minimum ~5 plays).

Hashed ID vs numeric ID

Wistia uses hashed IDs (alphanumeric strings like abc123def4) in most API endpoints. Don’t confuse these with numeric media IDs. You can find the hashed ID in the video’s embed URL or via GET /v1/medias.json.

Drop-off detection threshold

The 10% threshold is configurable. For shorter videos (under 60s), tighten to 5% — a 10% drop in a short video is more significant. For long-form (10+ min), relax to 15% to avoid false positives from natural attention fluctuation.

What’s Next

Wistia Integration

Back to Wistia integration overview

Viewer-Level Persona Mapping

Map viewers to psychographic personas

CTA Performance × Focus Group

Optimize CTA placement and messaging

Mave Agent

Full reference for POST /api/v1/mave/chat

Viewer-Level Persona Mapping

CTA Performance × Focus Group

⌘I

​Scenario

​Architecture

​Code

​Example Output

​Error Handling

​What’s Next

Wistia Integration

Viewer-Level Persona Mapping

CTA Performance × Focus Group

Mave Agent

Scenario

Architecture

Code

Example Output

Error Handling

What’s Next