SafeWorld Ads

SafeWorld AdsDevelopers

Developer guide.

There are two things you can add: a banner you paste into a page, and rewarded ads that your server starts for a player. You get your keys from the publisher console.

Rewarded ads.

Your server asks us for a session for one player. The player opens the link. We tell your server when the reward is confirmed.

1. Ask for a session

Do this from your server with your server key (swk_srv_…). We reject app keys here, so a game client can't start sessions by itself.

  • placementId is the placement from your console.
  • externalUserRef is your own ID for the player. We only keep a hash of it.
  • The link you get back works for 30 minutes.
curl https://app.safeworld.cc/v1/sdk/server/sessions \
  -H "Authorization: Bearer swk_srv_..." \
  -H "Content-Type: application/json" \
  -d '{"placementId":"PLACEMENT_ID","externalUserRef":"player-8841"}'

# 200
{
  "sessionUrl": "https://app.safeworld.cc/play/...",
  "token": "...",
  "expiresAt": "2026-11-14T16:30:00.000Z",
  "publisherUserId": "...",
  "linked": false
}

2. Send the player to the link

Open sessionUrl in a browser tab or a web view. The player picks an ad and does it. They don't need an account.

3. Give the reward when we call you

When a reward is confirmed we POST to the callback URL you set in the console. Check the signature, then give the player what's in hostReward.

POST /your/callback
X-SafeWorld-Event: reward_settled
X-SafeWorld-Timestamp: 1794670000
X-SafeWorld-Signature: 9f2c...   # hex

{
  "event": "reward_settled",
  "claimId": "...",
  "engagementId": "...",
  "placementId": "...",
  "publisherUserId": "...",
  "rewardIssuer": "publisher",
  "hostReward": { "currency": "Gems", "amount": 120 },
  "settledAt": "2026-11-14T16:04:11.000Z"
}

Checking the signature.

The signature is an HMAC-SHA256 of the timestamp, a dot and the raw request body, using your callback secret, written as hex. Type into the calculator to compare with your own code.

X-SafeWorld-Signature

Worked out in your browser. Nothing you type here is sent anywhere.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, headers, secret) {
  const ts = headers['x-safeworld-timestamp'];
  const sig = headers['x-safeworld-signature'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const want = createHmac('sha256', secret)
    .update(ts + '.' + rawBody)
    .digest('hex');
  const a = Buffer.from(want), b = Buffer.from(String(sig));
  return a.length === b.length && timingSafeEqual(a, b);
}
  • Use the raw body, before you parse the JSON.
  • Reject timestamps more than 5 minutes off your clock.
  • Use claimId to make sure you only give each reward once.
  • The console has a button that sends a test callback (event: "test"). It gives nothing.

Keys and errors.

  • App key swk_pub_

    Public. It tells us which site a banner belongs to. Safe to put in a web page.

  • Server key swk_srv_

    Secret. We show it once when you create it and only store a hash. Keep it on your server.

  • 401 server_key_requiredYou sent an app key, or no key at all.
  • 401 invalid_keyWe don't know that server key, or it was revoked.
  • 404 placement_not_foundThat placement doesn't exist or isn't yours.
  • 400 invalid_requestThe body is missing a field, or a field is too long.

Want keys for your game or site?

Request access