Integrating Loyalty in Your Game

curl https://invo.network/api/sdk/loyalty/me/card \
  -H "Authorization: Bearer $PLAYER_TOKEN"

import { InvoClient } from "@invonetwork/web-sdk";

const invo = new InvoClient({ token: playerToken, baseUrl: "https://invo.network" });
const { cards } = await invo.getMyRewards();   // cards[].steps[].progress, cards[].rewards[].codeMasked

{
  "card_version": 1,
  "cards": [
    {
      "card_version": 1,
      "mode": "live",
      "program_id": "lpb_8f2c41",
      "quest_id": "qst_51a0",
      "quest_version": 2,
      "campaign_id": "prg_7d11",
      "title": "Weekend Warrior",
      "description": "Top up, play five matches and grab a reward.",
      "brand": { "name": "Example Brand", "logo_url": "https://.../brand-logo.png" },
      "art_url": "https://.../card-art.png",
      "reward": { "reward_id": "rwd_25gc", "name": "$25 gift card" },
      "order_mode": "ordered",
      "status": "in_progress",
      "starts_at": "2026-10-01T00:00:00+00:00",
      "ends_at": "2026-10-31T23:59:59+00:00",
      "completion_hours": 168,
      "completion_note": null,
      "window_ends_at": "2026-10-09T18:30:00+00:00",
      "completed_at": null,
      "steps_required": 3,
      "steps_complete": 1,
      "steps": [
        { "step_id": "0e5c...", "index": 0, "action": "buy_currency",
          "label": "Buy currency", "summary": "Buy currency (at least $10.00)",
          "window_hours": null, "state": "complete",
          "progress": { "current": 1, "target": 1 } },
        { "step_id": "7a91...", "index": 1, "action": "custom_event",
          "label": "A custom game event", "summary": "A custom game event (match_completed, 5 times)",
          "window_hours": null, "state": "open",
          "progress": { "current": 3, "target": 5 } },
        { "step_id": "c4d2...", "index": 2, "action": "transfer_out",
          "label": "Transfer currency to another game", "summary": "Transfer currency to another game",
          "window_hours": null, "state": "locked",
          "progress": { "current": 0, "target": 1 } }
      ],
      "rewards": []
    }
  ]
}

function stepLabel(step) {
  if (step.state === "complete") return "Done";
  if (step.state === "locked") return "Locked";
  if (step.progress) return step.progress.current + " / " + step.progress.target;  // "3 / 5"
  return "Open";
}

{
  "items": [
    {
      "quest_id": "qst_51a0",
      "quest_version": 2,
      "program_id": "prg_7d11",
      "campaign": true,
      "title": "Weekend Warrior",
      "reward_ref": "rwd_25gc",
      "xp_award": 0,
      "objectives_required": 3,
      "objectives_complete": 1,
      "progress_state": "in_progress",
      "window_ends_at": "2026-10-09T18:30:00+00:00",
      "completed_at": null
    }
  ]
}

{
  "items": [
    {
      "vault_entry_id": "6f1d2c0e-8b7a-4e7c-9a51-0d3f6a2b9c11",
      "reward_ref": "rwd_25gc",
      "program_id": "prg_7d11",
      "quest_id": "qst_51a0",
      "units": "1",
      "state": "unlocked",
      "unlocked_at": "2026-10-05T14:02:11+00:00",
      "expires_at": "2026-12-31T23:59:59+00:00",
      "redeemed_at": null,
      "code_masked": null
    }
  ]
}

curl -X POST https://invo.network/api/sdk/loyalty/me/vault/6f1d2c0e-8b7a-4e7c-9a51-0d3f6a2b9c11/redeem \
  -H "Authorization: Bearer $PLAYER_TOKEN"

{
  "vault_entry_id": "6f1d2c0e-8b7a-4e7c-9a51-0d3f6a2b9c11",
  "reward_ref": "rwd_25gc",
  "state": "redeemed",
  "redeemed_at": "2026-10-05T14:05:40+00:00",
  "code": "GC-7Q2M-XK4P-ABCD",
  "code_masked": "••••ABCD",
  "revealed_again": false,
  "reveal_until": "<until when this player can see the code again>"
}

try {
  const { code } = await invo.redeemReward(reward.vaultEntryId);
  showToPlayer(code);                    // show it now; never log, cache or store it
} catch (err) {
  if (err.isRewardAlreadyRedeemed) { /* already redeemed and can no longer be shown */ }
  else if (err.isRewardNotFound) { /* no such reward for this player */ }
  else if (err.isRewardExpired) { /* expired before it was redeemed */ }
  else throw err;
}

curl -X POST https://invo.network/api/sdk/loyalty/me/rewards-page \
  -H "Authorization: Bearer $PLAYER_TOKEN"

const { url } = await invo.getRewardsPageLink();
window.open(url);

{
  "url": "https://invo.network/loyalty/rewards#t=...",
  "expires_at": "2026-10-05T14:20:00+00:00"
}

curl -X POST https://invo.network/api/sdk/loyalty/server-events \
  -H "X-Game-Secret-Key: $INVO_GAME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "player_email": "player@example.com",
    "event_type": "game.custom.recorded",
    "event_id": "3b9e7c2a-1f4d-4a8e-9c6b-5d2e8f1a7b30",
    "occurred_at": "2026-10-05T14:00:00Z",
    "payload": { "event_name": "match_completed" }
  }'

import { randomUUID } from "node:crypto";

const BASE = process.env.INVO_BASE_URL;            // https://invo.network  |  https://sandbox.invo.network/sandbox
const GAME_SECRET = process.env.INVO_GAME_SECRET;  // server-side only

async function reportMatchCompleted(playerEmail, eventId = randomUUID()) {
  const res = await fetch(BASE + "/api/sdk/loyalty/server-events", {
    method: "POST",
    headers: { "Content-Type": "application/json", "X-Game-Secret-Key": GAME_SECRET },
    body: JSON.stringify({
      player_email: playerEmail,
      event_type: "game.custom.recorded",
      event_id: eventId,                 // keep it, and resend the same id on retry
      payload: { event_name: "match_completed" },
    }),
  });
  return { status: res.status, json: await res.json().catch(() => ({})) };
}

import os, uuid, requests

BASE = os.environ["INVO_BASE_URL"]            # https://invo.network  |  https://sandbox.invo.network/sandbox
GAME_SECRET = os.environ["INVO_GAME_SECRET"]  # server-side only

def report_match_completed(player_email, event_id=None):
    event_id = event_id or str(uuid.uuid4())  # keep it, and resend the same id on retry
    r = requests.post(BASE + "/api/sdk/loyalty/server-events",
                      headers={"X-Game-Secret-Key": GAME_SECRET},
                      json={"player_email": player_email,
                            "event_type": "game.custom.recorded",
                            "event_id": event_id,
                            "payload": {"event_name": "match_completed"}},
                      timeout=30)
    return r.status_code, r.json()

curl -X POST https://invo.network/api/sdk/loyalty/events \
  -H "Authorization: Bearer $PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "game.milestone.reached",
    "event_id": "9a4c1e2b-7d3f-4b6a-8e5c-2f1a0b9d8c77",
    "payload": { "milestone_key": "level_10" }
  }'

curl -G https://invo.network/api/sdk/loyalty/players/rewards \
  --data-urlencode "player_email=player@example.com" \
  -H "X-Game-Secret-Key: $INVO_GAME_SECRET"

import { InvoServer } from "@invonetwork/web-sdk/server";

const invo = new InvoServer({
  gameSecret: process.env.INVO_GAME_SECRET!,   // server-side only
  baseUrl: process.env.INVO_BASE_URL!,         // https://invo.network  |  https://sandbox.invo.network/sandbox
});

const { cards } = await invo.getPlayerRewards("player@example.com");
for (const card of cards) {
  for (const step of card.steps) {
    if (step.progress) console.log(step.summary, step.progress.current + " / " + step.progress.target);
  }
}

const url = new URL(process.env.INVO_BASE_URL + "/api/sdk/loyalty/players/rewards");
url.searchParams.set("player_email", "player@example.com");

const res = await fetch(url, { headers: { "X-Game-Secret-Key": process.env.INVO_GAME_SECRET } });
const { cards } = await res.json();

import os
from invonetwork import InvoServer

invo = InvoServer(
    game_secret=os.environ["INVO_GAME_SECRET"],   # server-side only
    base_url=os.environ["INVO_BASE_URL"],         # https://invo.network  |  https://sandbox.invo.network/sandbox
)

result = invo.get_player_rewards("player@example.com")
for card in result.cards:
    print(card.title, card.steps_complete, "/", card.steps_required)
    for step in card.steps:
        if step.progress is not None:          # None: render step.state alone
            print(" ", step.summary, step.progress.current, "/", step.progress.target)

import os, requests

r = requests.get(os.environ["INVO_BASE_URL"] + "/api/sdk/loyalty/players/rewards",
                 params={"player_email": "player@example.com"},
                 headers={"X-Game-Secret-Key": os.environ["INVO_GAME_SECRET"]},
                 timeout=30)
cards = r.json()["cards"]