SDK and Integration

There is no SDK to install. Qyren is a REST API. All calls are server-to-server from your game backend. You will use three endpoints:

POST /v1/ingest — stream in player events (sessions, purchases, currency, progression).
POST /v1/offers/import — upload your offer catalog once, and re-upload when it changes.
POST /v1/recommend — ask Qyren which offer to show a specific player right now.

That’s it. Everything else (economy health, dashboards, alerts) is derived from the data you send on /v1/ingest.

The three-call flow

Game server ──(1) events as they happen──► /v1/ingest
Game server ──(2) offer catalog, once────► /v1/offers/import
Game server ──(3) "what to show player X"► /v1/recommend ──► [offer_id, ...]

1. Send events

Batch up to 100 events per call. Don’t wait for a batch to fill — flush every few seconds or when you reach ~50 events, whichever comes first. Full event schema: Events. Minimum events you should log for Qyren to work:

session_start and session_end
purchase (with revenue_usd, offer_id, transaction_id, store, is_first_purchase)
currency_earned and currency_spent (with balance_after — this is how we track inflation)
offer_impression every time an offer is shown on screen
offer_click when a player taps/clicks it

If you skip offer_impression, we cannot compute conversion rate and recommendations will be weaker.

2. Import your offer catalog

Upload every offer you sell, once. Re-upload whenever the catalog changes (new offer, price change, removal).

curl -X POST https://api.qyren.ai/v1/offers/import \
  -H "Authorization: Bearer qyr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offers": [
      {
        "external_id": "starter_bundle_01",
        "name": "Starter Bundle",
        "price_usd": 4.99,
        "price_tier": "starter",
        "contents_json": "{\"gems\":100,\"gold\":5000,\"hero_token\":1}",
        "is_active": true
      }
    ]
  }'

The game_id is resolved from your API key. external_id is your stable ID and acts as the upsert key on re-import. See Offers for the full offer schema.

3. Ask for a recommendation

When a player hits a trigger (opens the shop, beats a boss, levels up), ask Qyren what to show:

curl -X POST https://api.qyren.ai/v1/recommend \
  -H "Authorization: Bearer qyr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "game_id": "origins_of_lume",
    "player_id": "player_12345",
    "placement": "shop_main",
    "max_offers": 3
  }'

The response gives you an ordered list of offer IDs. Display them top to bottom. When you actually show them, log offer_impression events — this is how Qyren learns what works.

Latency expectations

/v1/ingest: under 50ms at p95. Safe to call inline with gameplay.
/v1/recommend: under 150ms at p95. Still fine for shop-open triggers. If your trigger is inside a tight loop (e.g. end-of-battle popup), pre-fetch at session start and cache for a few minutes.

Graceful degradation

If Qyren is ever unreachable, your game should fall back to a default offer list. Never block gameplay waiting on Qyren. A 500ms timeout on /v1/recommend is reasonable.

Getting Started

Core Concepts

Economy Health

Recommendations

Billing

Integration

API Reference

Glossary

SDK and Integration

The three-call flow

1. Send events

2. Import your offer catalog

3. Ask for a recommendation

Latency expectations

Graceful degradation

​The three-call flow

​1. Send events

​2. Import your offer catalog

​3. Ask for a recommendation

​Latency expectations

​Graceful degradation

The three-call flow

1. Send events

2. Import your offer catalog

3. Ask for a recommendation

Latency expectations

Graceful degradation