Practical Guides

Universal Links (iOS)

Universal Links allow iOS to open your app directly from a URL — no redirect page, no browser flash. Requires configuration in both your app and the server.

Step 1 — Configure the Server

# .env
APPLE_TEAM_ID=AB12CD34EF       # 10-char Team ID from developer.apple.com
APPLE_BUNDLE_ID=com.yourco.app  # Must match your Xcode bundle ID exactly

The server will automatically serve the AASA file at /.well-known/apple-app-site-association.

Step 2 — Enable in Xcode

1. Open your project in Xcode → select the target → Signing & Capabilities
2. Click + Capability → select Associated Domains
3. Add your domain with the applinks: prefix:

   applinks:links.yourapp.com

   No https://, no trailing slash, no wildcard (*). Just the hostname.

4. Build and install on a device (Simulator does not support Universal Links)

Step 3 — Verify the AASA File

# Check the file is accessible and valid JSON
curl https://links.yourapp.com/.well-known/apple-app-site-association | jq .

# Use Apple's AASA validator
open https://branch.io/resources/aasa-validator/

Step 4 — Handle Universal Links in Your App

// SwiftUI
.onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { activity in
    guard let url = activity.webpageURL else { return }
    Task {
        if case .matched(let data) = await DeepLinkSDK.shared.handleOpenURL(url) {
            router.navigate(to: data.customData)
        }
    }
}

App Links (Android)

App Links allow Android to open your app directly from an HTTP URL, without showing a disambiguation dialog.

Step 1 — Configure the Server

# .env
ANDROID_PACKAGE=com.yourco.app
ANDROID_SHA256=AA:BB:CC:DD:...  # SHA-256 of your signing certificate

# Get your SHA-256 fingerprint:
keytool -list -v -keystore release.jks | grep SHA256

Step 2 — Configure AndroidManifest.xml

<activity android:name=".MainActivity">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
      android:scheme="https"
      android:host="links.yourapp.com" />
  </intent-filter>
</activity>

Step 3 — Verify the assetlinks.json File

# Check the file
curl https://links.yourapp.com/.well-known/assetlinks.json | jq .

# Use Google's Digital Asset Links validator
open https://developers.google.com/digital-asset-links/tools/generator

Step 4 — Handle App Links in Your App

// Handle both cold start and foreground intent
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent.data?.let { handleDeepLink(it) }
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    intent.data?.let { handleDeepLink(it) }
}

private fun handleDeepLink(uri: Uri) = lifecycleScope.launch {
    val result = DeepLinkSDK.handleOpenUrl(uri)
    if (result is DeepLinkResult.Matched) navigate(result.data)
}

Webhooks (HTTP / Pub/Sub)

DeepLink Server can send real-time HTTP POST notifications or publish to Google Cloud Pub/Sub when events occur. You can configure multiple webhook endpoints per tenant, each with its own URL, authentication, and event filter.

Endpoint Properties

Each webhook endpoint supports the following fields:

Routed Events

The following event types can be routed to webhook endpoints:

redirect resolve deferred event.* referral.claim banner.click banner.impression test.ping

Create an Endpoint

# Create a new webhook endpoint
curl -X POST /api/v1/webhooks/endpoints \
  -H "X-Api-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name":        "CRM sync",
    "url":         "https://crm.example.com/hooks/deeplink",
    "hmac_secret": "whsec_a1b2c3d4...",
    "api_key":     "sk-crm-xyz",
    "events":      ["redirect", "event.*", "referral.claim"],
    "active":      true
  }'

Manage Endpoints

# List all endpoints
curl /api/v1/webhooks/endpoints -H "X-Api-Key: your-key"

# Update an endpoint (e.g. pause delivery)
curl -X PATCH /api/v1/webhooks/endpoints/ep_abc123 \
  -H "X-Api-Key: your-key" \
  -d '{ "active": false }'

# Delete an endpoint
curl -X DELETE /api/v1/webhooks/endpoints/ep_abc123 \
  -H "X-Api-Key: your-key"

Authentication Headers

Every webhook delivery includes two authentication headers:

1. X-Deeplink-Signature — HMAC-SHA256 of the raw request body, computed with the endpoint's hmac_secret. The value is prefixed with sha256=.

   X-Deeplink-Signature: sha256=e3b0c44298fc1c14...

2. X-Api-Key — the static API key configured on the endpoint, sent as-is.

   X-Api-Key: sk-crm-xyz

HMAC Signature Verification

// Node.js verification
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const actual = signature.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(actual, 'hex')
  );
}

// Express route handler
app.post('/hooks/deeplink', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-deeplink-signature'];
  if (!verifyWebhook(req.body, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.sendStatus(200);
});

Webhook Payload

{
  "event":      "redirect",
  "tenant":     "my-company",
  "timestamp":  "2026-04-11T10:00:00Z",
  "endpoint_id": "ep_abc123",
  "data": {
    "slug":     "summer-sale",
    "platform": "ios",
    "country":  "FR",
    "matched":  false
  }
}

Google Cloud Pub/Sub Delivery

As an alternative to HTTP, you can route events to a Pub/Sub topic for parallel, high-throughput processing.

# Create a Pub/Sub endpoint
curl -X POST /api/v1/webhooks/endpoints \
  -H "X-Api-Key: your-key" \
  -d '{
    "name":    "Analytics pipeline",
    "type":    "pubsub",
    "topic":   "projects/my-gcp-project/topics/deeplink-events",
    "service_account_json": "{ ... }",
    "events":  ["redirect", "resolve", "deferred"],
    "active":  true
  }'

Test Ping

Send a test.ping event to a specific endpoint (or all active endpoints) to verify connectivity.

# Send test ping to a specific endpoint
curl -X POST /api/v1/webhooks/test \
  -H "X-Api-Key: your-key" \
  -d '{ "endpoint_id": "ep_abc123" }'

# Send test ping to all active endpoints
curl -X POST /api/v1/webhooks/test \
  -H "X-Api-Key: your-key"

Smart Banner

The Smart Banner shows mobile web visitors an "Open in App" prompt, driving them to install or open your app with the correct deep link context.

Embed the Script

<!-- Add to <head> on every page of your web site -->
<script
  src="https://links.yourapp.com/api/v1/banner/your-tenant/banner.js"
  data-position="top"
  data-dismiss="session"
></script>

Per-Page Configuration

<!-- On a product page, pass the specific link slug -->
<script
  src="https://links.yourapp.com/api/v1/banner/your-tenant/banner.js"
  data-link-slug="summer-sale"
  data-position="bottom"
  data-dismiss="permanent"
  data-theme="dark"
></script>

JavaScript API

// Control the banner programmatically
window.DeepLinkBanner.show();
window.DeepLinkBanner.hide();
window.DeepLinkBanner.setLink('product-42');

// Listen to events
window.DeepLinkBanner.on('open', () => console.log('User tapped Open in App'));
window.DeepLinkBanner.on('dismiss', () => console.log('Banner dismissed'));

A/B Testing

Use the custom_data field and analytics query engine to implement A/B tests on deep link campaigns.

Create Variants

# Variant A — original
curl -X POST /api/v1/links -d '{
  "title": "Summer Sale — A",
  "campaign": "summer-ab",
  "source": "email",
  "custom_data": { "variant": "A", "cta": "Shop Now" },
  "web_url": "https://example.com/sale"
}'

# Variant B — control
curl -X POST /api/v1/links -d '{
  "title": "Summer Sale — B",
  "campaign": "summer-ab",
  "source": "email",
  "custom_data": { "variant": "B", "cta": "Get 20% Off" },
  "web_url": "https://example.com/sale?v=b"
}'

Analyze Results

# Compare installs by campaign source
curl -X POST /api/v1/analytics/query \
  -d '{
    "filters": { "campaign": "summer-ab" },
    "group_by": ["slug", "title"],
    "metrics": ["clicks", "installs", "conversion_rate"],
    "order_by": "conversion_rate",
    "order": "desc"
  }'

Statistical Significance

Custom Events

Track meaningful actions in your app and attribute them to the deep link that drove the user.

Common Event Patterns

await sdk.trackEvent({
  name: 'purchase',
  linkSlug: data.slug,
  properties: {
    product_id: '42',
    category: 'electronics',
  },
  revenue: 99.99,
  currency: 'EUR',
});

await sdk.trackEvent({
  name: 'signup',
  linkSlug: data.slug,
  properties: {
    method: 'email',
    plan: 'free',
  },
});

await sdk.trackEvent({
  name: 'level_complete',
  linkSlug: data.slug,
  properties: {
    level: '5',
    score: '1420',
    time_s: '142',
  },
});

await sdk.trackEvent({
  name: 'subscribe',
  linkSlug: data.slug,
  properties: {
    plan: 'pro',
    billing: 'annual',
  },
  revenue: 119.88,
  currency: 'USD',
});

View Event Funnel

# See the full funnel for a campaign
curl "/api/v1/funnel?days=30&link_slug=summer-sale"

# Query event details
curl -X POST /api/v1/analytics/query -d '{
  "filters": { "campaign": "summer_2025" },
  "group_by": ["date"],
  "metrics": ["clicks", "installs"]
}'

Data Export (GCS / S3)

Export event data to your own data warehouse for long-term storage and custom analytics. DeepLink Server supports BigQuery streaming, Google Cloud Storage batch export, and Amazon S3 batch export.

Supported Destinations

Configuration

Navigate to Settings > Data warehouse in the dashboard, or use the API:

# Get current export configuration
curl /api/v1/export/config -H "X-Api-Key: your-key"

# Configure BigQuery streaming
curl -X PUT /api/v1/export/config \
  -H "X-Api-Key: your-key" \
  -d '{
    "type":       "bigquery",
    "project_id": "my-gcp-project",
    "dataset":    "deeplink_events",
    "table":      "raw_events",
    "service_account_json": "{ ... }"
  }'

# Configure GCS batch export
curl -X PUT /api/v1/export/config \
  -H "X-Api-Key: your-key" \
  -d '{
    "type":       "gcs",
    "bucket":     "my-deeplink-exports",
    "prefix":     "events/",
    "schedule":   "hourly",
    "service_account_json": "{ ... }"
  }'

# Configure S3 batch export
curl -X PUT /api/v1/export/config \
  -H "X-Api-Key: your-key" \
  -d '{
    "type":              "s3",
    "bucket":            "my-deeplink-exports",
    "prefix":            "events/",
    "region":            "eu-west-1",
    "schedule":          "daily",
    "aws_access_key_id": "AKIA...",
    "aws_secret_access_key": "..."
  }'

Test Connection

# Verify credentials and write permissions
curl -X POST /api/v1/export/test -H "X-Api-Key: your-key"

Manual Export

# Trigger an immediate export run (batch destinations only)
curl -X POST /api/v1/export/run \
  -H "X-Api-Key: your-key" \
  -d '{
    "from": "2026-04-01T00:00:00Z",
    "to":   "2026-04-18T00:00:00Z"
  }'

Settings & Configuration

Manage your account, team access, branding, API keys, and domain configuration from the Settings page in the dashboard.

Account

Update your profile information, change your password, and enable two-factor authentication (2FA) via TOTP.

1. Navigate to Settings > Account
2. Update your display name and email address
3. To enable 2FA, click Enable two-factor authentication, scan the QR code with your authenticator app, and enter the verification code

SSO / SAML

Connect your identity provider (Okta, Azure AD, or any SAML 2.0 IdP) for single sign-on.

1. Navigate to Settings > SSO/SAML
2. Enter your IdP's Metadata URL (e.g. https://your-org.okta.com/app/xxx/sso/saml/metadata)
3. Copy the following values into your IdP configuration:

   # Entity ID (Audience URI)
   https://links.yourapp.com/auth/saml/metadata
   
   # ACS URL (Reply URL)
   https://links.yourapp.com/auth/saml/acs

4. Click Test connection to verify the SAML handshake before enforcing SSO

Brand

Customize the visual identity used on the redirect page, transactional emails, and smart banners.

# Update branding via API
curl -X PATCH /api/v1/tenants/current \
  -H "X-Api-Key: your-key" \
  -d '{
    "brand": {
      "logo_url":     "https://cdn.example.com/logo.svg",
      "accent_color": "#4F46E5"
    }
  }'

The logo_url is displayed on the redirect interstitial page and in email templates. The accent_color is used for buttons, links, and the smart banner background.

API Keys

Create, rotate, and revoke API keys for programmatic access.

1. Navigate to Settings > API Keys
2. Click Create key and give it a descriptive name (e.g. "CI/CD pipeline")
3. Copy the key immediately -- it is only shown once
4. To rotate a key, click Rotate. The old key remains valid for 24 hours to allow a graceful migration
5. To revoke a key, click Revoke. The key is invalidated immediately

Domains (Custom CNAME)

Use your own domain (e.g. links.yourapp.com) instead of the default subdomain.

1. Navigate to Settings > Domains
2. Add your custom domain and create a CNAME record in your DNS provider:

   links.yourapp.com.  CNAME  ingress.deeplink-server.com.

3. Click Verify to confirm DNS propagation. A TLS certificate is provisioned automatically via Let's Encrypt

Setup détaillé — full walkthrough

1. 1. Plan check — custom domain requires Pro or Enterprise plan
2. 2. Add domain — Settings → Domains → "Add custom domain" → enter links.yourapp.com → DeepLink generates a verification token
3. 3. Two DNS records to create:

   # 1. CNAME for traffic routing
   links.yourapp.com.  CNAME  ingress.deeplink-server.com.
   
   # 2. TXT for ownership verification
   _deeplink-verify.links.yourapp.com.  TXT  "dlk-verify=abc123def456..."

4. 4. Verify — click "Verify" in dashboard. DeepLink polls DNS every 30s for up to 10 minutes. Status shifts: pending → dns_verified → ssl_issuing → active
5. 5. SSL provisioning — automatic via Let's Encrypt ACME HTTP-01 challenge. Cert renewed 30 days before expiry. Visible in dashboard with expiry date
6. 6. AASA / assetlinks.json — automatically served on the new domain at /.well-known/apple-app-site-association and /.well-known/assetlinks.json

Mobile Apps

Register your mobile apps so the server can generate the correct platform association files.

1. Navigate to Settings > Mobile Apps
2. iOS — enter your Apple Team ID and Bundle ID. The server generates the apple-app-site-association (AASA) file automatically at:

   https://links.yourapp.com/.well-known/apple-app-site-association

3. Android — enter your package name and SHA-256 signing certificate fingerprint. The server generates the assetlinks.json file at:

   https://links.yourapp.com/.well-known/assetlinks.json

Fraud Detection

DeepLink Server includes a multi-layer fraud-detection engine. Each click receives a fraud_score (0-100) computed at insertion by src/services/fraud-detector.js, a fraud_flags JSON array listing triggered rules, and a suspicious=true boolean if the score crosses the tenant threshold.

Scoring rules

Thresholds

• < 40 — legit, included in all KPIs
• 40-69 — flagged (visible in dashboard, not auto-excluded)
• ≥ 70 — suspicious=true (excluded from default KPIs, recoverable via filter)

Click row example

{
  "id": "clk_abc",
  "link_id": "summer-sale",
  "platform": "android",
  "fraud_score": 45,
  "fraud_flags": ["datacenter_ip", "missing_referer"],
  "suspicious": false,
  "ip_hash": "a3f8...c2"
}

IP Deduplication

Clicks from the same IP within a short window are deduplicated. The ip_hash (SHA-256 of the IP) is stored per click — never the raw IP address.

Bot Filtering

The server filters known bot user agents using a regularly-updated list. Filtered clicks are not counted in analytics.

Click Cap Enforcement

Use max_clicks on links to limit exposure on promotional campaigns. Once the cap is hit, the link returns 410 Gone.

Targeting Rules

Use targeting_rules.allow_countries and allow_devices to restrict links to specific audiences and prevent off-target click fraud.

Fingerprint Analysis

The deferred match uses probabilistic fingerprinting (SHA-256 of IP + UA + date). A 2-day window limits replay attacks while handling timezone edge cases.

Audit Log Monitoring

# Look for suspicious patterns: many deletes, rapid link creation
curl "/api/v1/audit?action=delete&limit=50"

# Check for high-volume clicks from single IPs
curl -X POST /api/v1/analytics/query -d '{
  "filters": { "matched": 0 },
  "group_by": ["country", "platform"],
  "metrics": ["clicks", "unique_ips"],
  "order_by": "clicks",
  "order": "desc",
  "limit": 20
}'

CLI Reference — deeplink command-line tool

Node.js CLI to automate common operations from terminal/CI: rotate API keys, batch-create links, export audit, run scheduled reports. Critical for CI/CD (e.g. create a deeplink at every mobile release).

Installation (3 methods)

# Method 1 — npm global (production)
npm install -g @deeplink/cli
deeplink --version

# Method 2 — npx ad-hoc (no install)
npx @deeplink/cli links list

# Method 3 — checkout repo + local link (dev)
git clone https://github.com/deeplink/deeplink-server
cd deeplink-server
npm link cli/   # creates global binary pointing at cli/deeplink.js

Configuration (3 sources, ordered by priority)

1. CLI flags (max priority) — deeplink --api-url=https://api.deeplink.com --api-key=dlk_xxx --tenant=acme links list
2. Environment variables — DEEPLINK_API_URL, DEEPLINK_API_KEY, DEEPLINK_TENANT
3. Config file — ~/.deeplinkrc.json or ~/.deeplink/config.json:

   { "default": "prod", "profiles": {
     "prod":    { "api_url": "https://api.deeplink.com",    "api_key": "dlk_live_...", "tenant": "acme" },
     "staging": { "api_url": "https://api-stg.deeplink.com", "api_key": "dlk_test_..." }
   }}

   Switch profile: deeplink --profile=staging links list

Auth alternative — interactive login

deeplink login
# → opens browser at https://app.deeplink.com/cli-auth?token=<one-time>
# → user logs in + accepts, server returns a dedicated API key "CLI - <hostname>"
# → CLI persists token in ~/.deeplink/credentials (chmod 600)

Commands

Output formats

• --format=table (default, ASCII pretty-print) — human
• --format=json — pipe-friendly, | jq
• --format=csv — spreadsheet
• --format=ndjson — line-by-line streaming (large lists)

CI/CD use case — GitHub Actions

# .github/workflows/release.yml — create deeplink at every mobile release
- name: Create release deeplink
  run: |
    npx @deeplink/cli links create \
      --url="https://app.acme.com/release/${{ github.ref_name }}" \
      --campaign="release-${{ github.ref_name }}" \
      --tags="release,${{ github.ref_name }}" \
      --format=json > deeplink.json
  env:
    DEEPLINK_API_KEY: ${{ secrets.DEEPLINK_API_KEY }}
    DEEPLINK_TENANT: acme

Source: cli/deeplink.js (~600 lines) + cli/lib/ (commands, auth, output formatters).

Settings reference — 25 sous-pages organisées en 8 groupes

Référence complète des Settings après refacto v2 (ex-ADM-MIG). 25 sous-pages réparties en 8 groupes thématiques. Visibilité conditionnée par le rôle (admin ou super-admin). Source : SETTINGS_NAV dans public/js/dashboard.js:8962.

Search bar (⌘K) en haut de la sidebar Settings filtre par nom. Vue d'état (overview) en première position regroupe les KPIs config (badges configuré / partiel / non-configuré pour chaque sous-page).

Onboarding wizard — guide pas-à-pas du nouvel intégrateur

Le wizard accompagne un nouveau tenant de la création (config mobile) jusqu'au premier identify() appelé. Source : src/routes/onboarding.js, table onboarding_progress.

Workflow — 6 étapes

API endpoints

• GET /api/v1/onboarding — état des 6 steps + done_count + total_steps.
• PATCH /api/v1/onboarding — set manuellement un step done (utile si auto-check rate). Body : { step: "mobile_config", done: true }.
• POST /api/v1/onboarding/verify — re-vérifie les 6 steps en lisant la DB.

UX dashboard

┌─ Wizard d'intégration ─────────────────────────────┐
│ Étape 1/6 ✓ Configuration mobile (Bundle ID + Team)│
│ Étape 2/6 ✓ SDK intégré (clic SDK détecté)         │
│ Étape 3/6 ✓ Premier lien créé                      │
│ Étape 4/6 ✓ Premier clic enregistré                │
│ Étape 5/6 □ Premier event tracké  ← BLOCKER ICI    │
│ Étape 6/6 □ identify() appelé                      │
│                                                    │
│ ▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░  4/6 (67%)               │
│                                                    │
│ [ Vérifier maintenant ]   [ Documentation SDK → ]  │
└────────────────────────────────────────────────────┘

Troubleshoot par étape

Identity diagnostic admin

Outil admin pour résoudre les "pourquoi cet utilisateur n'est pas attribué" et autres écarts de chaîne d'identité. Disponible uniquement pour les administrateurs (rôle admin du tenant). Source : src/routes/identity.js.

Cas d'usage

Un utilisateur (Sarah, growth manager d'une boutique) signale : "J'ai cliqué sur la pub Facebook et installé l'app, mais je n'apparais pas comme attribuée à cette campagne dans le dashboard." L'admin doit comprendre où la chaîne click → install → identify s'est cassée.

Diagnostic temps réel

// Response 200
{
  "verdict": "warn",                              // "ok" | "warn" | "fail"
  "checks": [
    {
      "id": "sdk_instance_id_recent",
      "label": "SDK instance ID seen in clicks (last 1h)",
      "pass": true
    },
    {
      "id": "user_id_recent",
      "label": "user_id seen in events (last 1h)",
      "pass": true
    },
    {
      "id": "user_id_ratio_24h",
      "label": "user_id ratio in events (last 24h)",
      "value": "32%",
      "pass": false
    }
  ],
  "recommendations": [
    "Only 32% of events have a user_id. Ensure identify() is called for all authenticated users."
  ]
}

Workflow d'investigation pour le cas Sarah

1. Lancer le diagnostic : curl -H "Authorization: Bearer $JWT" $BASE/api/v1/identity/diagnostic. Si verdict=fail → check SDK + identify() manquant. Si verdict=warn → ratio user_id bas, l'événement de Sarah est probablement anonyme.
2. Inspecter le clic Facebook de Sarah dans Settings → Identity (page admin) ou directement en DB : SELECT * FROM clicks WHERE link_id = ? AND ip_hash = ? ORDER BY created_at DESC LIMIT 5. Vérifier sdk_instance_id, fingerprint, created_at.
3. Inspecter l'install via match_attempts ou events table — y a-t-il un event install/app_open avec le même sdk_instance_id ? Si oui → cookie déjà connecté.
4. Vérifier le merge identity via le graph (table identity_aliases) : le sdk_instance_id de Sarah est-il aliasé à son user_id ? Sinon, identify() n'a pas été appelé après login.
5. Backfill server-side si nécessaire (récupération d'attribution post-hoc) : POST /api/v1/identity avec {user_id, sdk_instance_id, source:"manual_recovery"}. Cette route audite l'opération.

3 patterns courants

Cf. également identity graph (vulgarisé) et chantier IDENT-QUAL livré pour le détail technique.

Audit log — investigation ops

L'audit log enregistre toute mutation administrative (création/modif/suppression de liens, changements de settings, login/logout, etc.). Endpoint admin-only, tenant-scoped pour les admins de tenants, traversable pour le super-admin main. Source : src/routes/audit.js, table audit_logs.

Schéma des entrées

API

3 cas d'usage concrets

Cas 1 — "Qui a modifié les paramètres SMTP la semaine dernière ?"

# Filtre resource_type + action + post-traitement par date côté client
curl -H "Authorization: Bearer $JWT" \
  "$BASE/api/v1/audit?resource_type=settings&action=update&limit=200" \
  | jq '.logs[] | select(.created_at > "2026-04-25" and (.diff | tostring | contains("smtp")))'

Résultat : liste des entrées avec actor_email, diff (champs SMTP modifiés old→new), timestamp. Si vide → personne n'a touché. Sinon vous savez qui prévenir.

Cas 2 — "Qui a créé ce lien Black Friday ?"

# Recherche par resource_id (slug du lien)
curl -H "Authorization: Bearer $JWT" \
  "$BASE/api/v1/audit?resource_type=link&action=create&limit=500" \
  | jq '.logs[] | select(.resource_id == "blackfriday-2026")'

Résultat : 1 entrée avec actor_email + diff (champs initiaux du lien) + ip. Si plusieurs → plusieurs créations historiques (le slug a peut-être été supprimé puis recréé).

Cas 3 — "Qui a supprimé la campagne X ?"

# action=delete + resource_type=campaign
curl -H "Authorization: Bearer $JWT" \
  "$BASE/api/v1/audit?resource_type=campaign&action=delete&limit=100" \
  | jq '.logs[]'

Sur les ressources delete, le diff capture l'état avant suppression (utile pour reconstruire si besoin). L'IP indique si c'était fait depuis le dashboard ou un script.

Bonnes pratiques investigation

• Toujours partir de la fenêtre temporelle la plus précise possible (passer le filtre côté serveur si limit ≤ 500 sinon paginer).
• Croiser avec le diff : si action=update mais aucune valeur modifiée dans diff → ré-enregistrement vide (peut indiquer un bug UI).
• Audit log non bloquant : si l'écriture échoue (exception), l'opération métier passe quand même. Donc 100% des actions ne sont pas garanties tracées (cf. services/audit.js try/catch).
• Export CSV/PDF : prévu via ROAD-G4-03 Audit log export (à instruire). En attendant, jq + redirection fichier suffit pour la plupart des audits ponctuels.

Cf. également errors catalog pour les codes applicatifs ; architecture.html pour le data model audit_logs.

Testing patterns — comment tester son intégration

Trois approches recommandées selon le besoin : (1) tenant sandbox sur l'instance partagée pour les tests end-to-end manuels, (2) mock SDK pour les tests unitaires côté client, (3) fixtures HTTP pour les tests d'intégration côté backend qui consomment l'API DeepLink.

1. Tenant sandbox — tests E2E manuels

Chaque tenant peut activer un mode sandbox via Settings → Advanced → Sandbox mode. Les liens créés en sandbox ont un préfixe distinct (sbx_) et leurs events sont isolés des stats de prod. Idéal pour valider une intégration avant le go-live.

• Aucun event sandbox ne contamine les rapports prod (filtrés par défaut).
• Quotas API doublés pendant la durée du test (cf. rate limits).
• Les webhooks sandbox sont taggés X-Deeplink-Mode: sandbox dans les headers.

2. Mock SDK — tests unitaires

Quand on teste son code applicatif (ex. logique post-deeplink-resolve), on ne veut pas que les tests fassent de vrais appels HTTP au serveur. Stub le SDK : retourner une réponse synchrone canned.

Node.js — Jest / Vitest

// __tests__/deeplink.test.js
const { jest } = require('@jest/globals');
const deeplink = require('@akeeli/deeplink-sdk-node');

jest.mock('@akeeli/deeplink-sdk-node');

deeplink.resolveLink.mockResolvedValue({
  link_id:  'lnk_abc',
  campaign: 'spring-2026',
  payload:  { sku: 'XYZ-42' }
});

test('handler reads campaign from resolved link', async () => {
  const r = await handler({ headers: { 'x-deeplink-id': 'lnk_abc' } });
  expect(r.campaign).toBe('spring-2026');
});

Python — pytest + responses

import responses
from deeplink import Client

@responses.activate
def test_resolve_link():
    responses.add(
        responses.GET,
        "https://api.deeplink.akeeli.dev/api/v1/links/lnk_abc",
        json={"link_id": "lnk_abc", "campaign": "spring-2026"},
        status=200,
    )
    c = Client(api_key="sbx_test")
    r = c.resolve_link("lnk_abc")
    assert r.campaign == "spring-2026"

Swift / iOS — XCTest + URLProtocol stub

import XCTest
@testable import AkeeliDeepLink

class MockURLProtocol: URLProtocol {
  static var stub: (Data, HTTPURLResponse)?
  override class func canInit(with: URLRequest) -> Bool { true }
  override func startLoading() {
    guard let (data, resp) = Self.stub else { return }
    client?.urlProtocol(self, didReceive: resp, cacheStoragePolicy: .notAllowed)
    client?.urlProtocol(self, didLoad: data)
    client?.urlProtocolDidFinishLoading(self)
  }
  override func stopLoading() {}
}

func testResolveLink() async throws {
  let body = #"{"link_id":"lnk_abc","campaign":"spring-2026"}"#.data(using: .utf8)!
  MockURLProtocol.stub = (body, HTTPURLResponse(...)!)
  let result = try await DeepLink.resolve(id: "lnk_abc")
  XCTAssertEqual(result.campaign, "spring-2026")
}

3. Fixtures HTTP — tests d'intégration côté serveur

Si ton backend appelle l'API DeepLink (ex. webhook receiver, batch import), enregistre les réponses réelles via nock (Node) / vcr.py (Python) lors du premier run, puis rejoue ensuite hors-ligne.

// Node — nock + recorded fixture
const nock = require('nock');
nock.back.fixtures = './tests/fixtures';
nock.back.setMode('record');          // au 1er run
nock.back.setMode('lockdown');        // CI : interdit le réseau, replay only

const { nockDone } = await nock.back('resolve_link.json');
const link = await deeplink.resolveLink('lnk_abc');
nockDone();

Bonnes pratiques

• Préférer tenant sandbox + smoke tests automatisés dans la CI staging plutôt que des mocks fragiles.
• Pour les tests unitaires : mock au niveau de la frontière HTTP (URLProtocol / nock / responses), pas au niveau du SDK lui-même → ainsi un upgrade SDK casse le mock si le contrat change.
• Les webhooks sont testables avec un tunnel ngrok ou via le webhook-tester interne.
• Quota gratuit du mode sandbox : 10 000 events/mois — au-delà, créer un tenant de test dédié.

Cf. errors catalog pour la liste des codes attendus quand on simule des cas d'erreur ; tests/ côté serveur pour des exemples de fixtures réelles.

Troubleshooting

Universal Links don't open the iOS app

• Check AASA file — curl -i https://yourdomain/.well-known/apple-app-site-association must return JSON with Content-Type: application/json (no .json extension)
• Verify Team ID + Bundle ID exactly match your app (case-sensitive)
• Reinstall the app — iOS caches AASA on install only. Restart device if uncached
• Test via Notes app (paste link) — Safari sometimes opens links in browser; Notes always uses Universal Links

App Links don't open the Android app

• Verify assetlinks.json served at root /.well-known/ with correct SHA-256 fingerprint
• Check autoVerify="true" in AndroidManifest.xml intent-filter
• Force re-verification: adb shell pm verify-app-links --re-verify your.package.name
• Inspect verification status: adb shell pm get-app-links your.package.name

Deferred deep link match fails

• Match window is 2 days from click — older clicks expired
• Fingerprint requires same public IP + UA family + date. Mobile data → Wi-Fi switch breaks the match
• Strict mode (strict_match=true) requires exact UA — useful for accuracy, increases false negatives
• Use ?force_match=link_slug on first launch to test the SDK integration in dev

Webhook never reaches our endpoint

• Check DLQ — Workflows → DLQ dashboard page lists all failed deliveries with full request/response
• Verify URL is HTTPS in production (safe-fetch rejects http://)
• HMAC mismatch? Verify X-DeepLink-Signature header against HMAC-SHA256(body, webhook_secret)
• Backoff retry: 1m / 5m / 30m / 2h / 12h, then abandoned. Replay manually from DLQ.

Custom domain stuck in "ssl_issuing"

• Let's Encrypt requires HTTP-01 challenge on port 80 — verify your CNAME doesn't drop port 80
• Rate limit: 50 cert requests / domain / week. Wait or contact support
• CAA DNS record? Add 0 issue "letsencrypt.org" to your domain

Logs don't show my error

• In-memory ring buffer (src/logger.js) loses logs on instance restart — Cloud Run restarts often
• Use the Cloud Logging viewer (Settings → Platform Logs) for persistent logs — requires GOOGLE_CLOUD_PROJECT + IAM roles/logging.viewer
• Filter by errorId from the API response — every error has a unique errorId UUID logged server-side