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.
Banners
Make a slot in the console under Display slots, then paste its tag where you want the ad.
- Three sizes: banner, sidebar and square.
- The app key (swk_pub_…) is public. It's fine to have it in your page source.
- The ad is drawn in a shadow root, so your CSS and ours don't clash.
- No cookies. One random ID in localStorage remembers "Not for me".
- If there's no ad to show, the slot stays empty.
<!-- where the ad should appear --> <div data-safeworld-slot="SLOT_ID" data-safeworld-key="swk_pub_..."></div> <script src="https://app.safeworld.cc/embed/display.js" async></script>
To preview a slot before you put it on your site, open /embed/demo.html?slot=SLOT_ID&key=swk_pub_…
If your site uses a Content-Security-Policy, add https://app.safeworld.cc to script-src and connect-src.
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.