Integration Guide

Scrya is a REST API — no SDK to install. If your engine can make HTTP requests, it can run Scrya ads. This guide covers the complete integration flow.

Authentication

All API calls require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key from the Scrya dashboard after registering as a developer.

Base URL

https://api.scrya.com/api/ads

Step 1: Enable Placements

Before your game can receive ads, enable placements:

POST /api/ads/placements/{game_id}
Content-Type: application/json

{
  "creator_id": "your_user_id",
  "placement_types": ["narrative_hook", "product_mention"],
  "revenue_share_pct": 70,
  "max_ads_per_session": 5,
  "blocked_advertisers": [],
  "blocked_categories": []
}

Key fields:

• placement_types — Which creative formats you accept
• revenue_share_pct — Your cut (0-100%, default 70%)
• max_ads_per_session — Fatigue limit per player session (1-50)
• blocked_advertisers — Advertiser IDs to block
• blocked_categories — Ad categories to block

Step 2: Match an Ad

When generating a game scene (dilemma, dialogue, cutscene), ask Scrya for the best matching ad:

POST /api/ads/match
{
  "game_id": "your_game_id",
  "user_id": "player_123",
  "player_geo": {
    "country_code": "US",
    "state_code": "CA",
    "city_name": "Los Angeles"
  },
  "game_context": {
    "theme_id": "3",
    "category": "simulation",
    "narrative": "The president faces a crisis in the situation room",
    "mood_tags": ["tense", "urgent"]
  },
  "session_id": "session_abc123"
}

Response (200 OK):

{
  "campaign_id": "camp_xxx",
  "creative_id": "crt_yyy",
  "narrative_hook": "As the monitors flicker, a familiar logo catches your eye...",
  "creative_type": "narrative_hook",
  "brand_name": "Acme Corp",
  "biased_pipeline": {
    "lighting": "warm golden hour",
    "effects": "cinematic widescreen, film grain"
  },
  "cpm_bid_cents": 200
}

If no ad matches, the response is 204 No Content — proceed with the scene as normal.

Step 3: Inject the Hook

Insert narrative_hook into your dialogue or narrator text. The hook is pre-written by the advertiser to sound natural.

If the response includes biased_pipeline, optionally apply those visual overrides to your scene renderer (lighting, effects, location).

Step 4: Record the Impression

After the player sees the ad-influenced scene, record the impression:

POST /api/ads/impressions
{
  "campaign_id": "camp_xxx",
  "creative_id": "crt_yyy",
  "game_id": "your_game_id"
}

This is what triggers payment. The advertiser is charged their CPM bid, and your revenue share is credited.

Error Handling

Rate Limits

Default rate limits:

• Match endpoint: 100 requests/minute per game
• Impression endpoint: 1,000 requests/minute per game
• Analytics endpoints: 30 requests/minute per API key

Next Steps

• 5-minute Quickstart — minimal working example
• Full API Reference — all 50+ endpoints
• How Matching Works — the 6-step pipeline
• Affinity Targeting — 8 affinity types deep dive
• Revenue Model — how you get paid