Offers API. Il suo design, le nostre offerte.
Riceva in JSON le offerte per ogni utente, con immagini, passaggi e ricompense già nella sua valuta, e le mostri nelle sue card, accanto ai suoi contenuti. Le ricompense arrivano tramite postback, come con l'offerwall.
- JSONREST su HTTPS
- 600Richieste al minuto
- OpenAPISpecifica inclusa
curl -G "https://api.moonetix.com/v1/offers" \
-d user_id=user_1234 -d country=US -d device=android \
-H "Authorization: Bearer $MOONETIX_API_KEY"Vada live in tre passaggi.
Copi il codice, sostituisca i segnaposto con i valori della sua dashboard in Offerwall, il suo offerwall, Integrazione, e faccia un test prima del lancio.
-
Richieda le offerte per un utente
Chiami l'API dal suo server con la chiave API della sua app, l'ID utente, il paese in cui si trova l'utente e il suo dispositivo o user agent. L'elenco esclude le offerte che l'utente ha già completato o che non può ancora ripetere.
Terminalecurl -G "https://api.moonetix.com/v1/offers" \ -d user_id=user_1234 -d country=US -d device=android \ -H "Authorization: Bearer $MOONETIX_API_KEY"offers.php<?php $query = http_build_query([ 'user_id' => $userId, 'country' => $countryCode, 'ua' => $_SERVER['HTTP_USER_AGENT'] ?? '', ]); $ch = curl_init('https://api.moonetix.com/v1/offers?' . $query); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey], ]); $data = json_decode((string)curl_exec($ch), true);offers.jsconst params = new URLSearchParams({ user_id: userId, country: countryCode, ua: req.headers['user-agent'] || '', }); const res = await fetch(`https://api.moonetix.com/v1/offers?${params}`, { headers: { Authorization: `Bearer ${process.env.MOONETIX_API_KEY}` }, }); const data = await res.json();offers.pyimport os, requests r = requests.get( "https://api.moonetix.com/v1/offers", params={"user_id": user_id, "country": country_code, "ua": user_agent}, headers={"Authorization": f"Bearer {os.environ['MOONETIX_API_KEY']}"}, timeout=10, ) data = r.json() -
Le mostri con il suo design
Ogni offerta include titolo, immagine, passaggi e la ricompensa nella sua valuta. Le mostri come preferisce e, quando l'utente ne sceglie una, lo mandi allo start_url dell'offerta. La pagina dell'offerta si apre su Moonetix e da lì lo porta all'inserzionista.
JSON{ "ok": true, "currency": "Coins", "offers": [ { "id": 58, "title": "Nova Quest: reach level 10", "reward": 975, "payout_usd": 1.5, "start_url": "https://wall.moonetix.com/..." } ] }offers.jsfor (const offer of data.offers) { list.append(card({ title: offer.title, reward: `${offer.reward} ${data.currency}`, href: offer.start_url, })); } -
Accrediti le ricompense con il postback
Ogni ricompensa raggiunge il suo server come postback firmato. Verifichi l'hash, aggiunga la ricompensa una volta per ID transazione e la riprenda se un postback successivo la storna. I postback non riusciti vengono ritentati fino a 5 volte.
Dashboard, scheda "Postback"https://yoursite.com/postback?user={user_id}&tx={transaction_id}&status={status}&reward={reward}&hash={hash}postback.php<?php $tx = $_GET['tx'] ?? ''; $userId = $_GET['user'] ?? ''; $reward = $_GET['reward'] ?? ''; $status = $_GET['status'] ?? ''; $secret = getenv('MOONETIX_POSTBACK_SECRET'); $expected = hash_hmac('sha256', "$tx:$userId:$reward:$status", $secret); if (!hash_equals($expected, $_GET['hash'] ?? '')) { http_response_code(403); exit; } if ($status === '1') { credit_once($userId, $tx, $reward); // once per transaction ID } elseif ($status === '2') { reverse_if_credited($userId, $tx, $reward); } http_response_code(200);postback.jsconst crypto = require('crypto'); app.get('/postback', (req, res) => { const { tx, user, reward, status, hash } = req.query; const secret = process.env.MOONETIX_POSTBACK_SECRET; const expected = crypto.createHmac('sha256', secret) .update(`${tx}:${user}:${reward}:${status}`) .digest('hex'); const valid = typeof hash === 'string' && hash.length === expected.length && crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected)); if (!valid) return res.sendStatus(403); if (status === '1') creditOnce(user, tx, reward); // once per transaction ID if (status === '2') reverseIfCredited(user, tx, reward); res.sendStatus(200); });postback.pyimport hmac, hashlib, os from flask import request, abort @app.get("/postback") def postback(): a = request.args parts = [a.get(k, "") for k in ("tx", "user", "reward", "status")] msg = ":".join(parts) secret = os.environ["MOONETIX_POSTBACK_SECRET"].encode() expected = hmac.new(secret, msg.encode(), hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, a.get("hash", "")): abort(403) if a.get("status") == "1": credit_once(a["user"], a["tx"], a["reward"]) # once per transaction ID elif a.get("status") == "2": reverse_if_credited(a["user"], a["tx"], a["reward"]) return "", 200
{
"title": "Nova Quest: reach level 10",
"goals": [
{ "name": "Create an account", "reward": 325 },
{ "name": "Reach level 10", "reward": 650 }
],
"reward": 975,
"start_url": "https://wall.moonetix.com/..."
}
- Crea un account+325
- Raggiungi il livello 10+650
Dal JSON al suo design
Ogni offerta arriva pronta da mostrare, con i passaggi e le ricompense già nella sua valuta.
Cosa le offre l'API
- Offerte per utente
Le offerte corrispondono al paese e al dispositivo che invia, e quelle che un utente ha già completato vengono escluse.
- Ricompense nella sua valuta
Ogni ricompensa è già calcolata con il suo tasso di cambio, la quota per gli utenti, l'arrotondamento e gli eventuali bonus attivi.
- Passaggi e immagini
Le offerte in più passaggi elencano ogni passaggio con la sua ricompensa, così può mostrare esattamente cosa paga.
- Sub ID
Invii fino a cinque valori propri. Vengono aggiunti a ogni start_url e tornano nel postback.
- Le offerte nascoste restano nascoste
Le offerte che nasconde nella pagina "Offerte" vengono escluse anche dall'API, così corrisponde al suo offerwall.
- Specifica OpenAPI
Un file openapi.json leggibile dalle macchine descrive ogni campo, pronto per i generatori di codice e gli agenti di coding basati sull'IA.
Lo testi, poi lo lanci.
Tutto ciò che deve verificare prima che utenti reali vedano il suo offerwall, con gli strumenti integrati nella sua dashboard.
Apri come utente di prova
In "Stato dell'integrazione", nella scheda "Integrazione", apra il suo offerwall come utente owner-test. Le visite di test non vengono conteggiate come utenti.
Chiamata all'API con curl
Richieda l'elenco per un ID utente di test e un paese in cui ci sono offerte attive, e apra uno start_url in un browser.
Invia un postback di prova
Scelga utente, stato e pagamento, e veda esattamente cosa ha risposto il suo server, con codice di risposta e tempo. Gli ID transazione di test iniziano con test_.
Test da una connessione normale
VPN, proxy, Tor e reti cloud sono bloccati, quindi faccia il test da Wi-Fi domestico o rete dati mobile, in un paese in cui ci sono offerte attive.
Checklist per il lancio
0 di 10 pronti
Pronto per il lancio. I suoi progressi sono salvati in questo browser.
Errori comuni, risolti in fretta.
Cosa potrebbe incontrare durante l'integrazione della Offers API, la causa e la soluzione.
400 invalid_countryUn parametro manca o è errato: invalid_user_id, invalid_country o invalid_device.
SoluzioneCorregga il parametro indicato nel codice di errore.
401 invalid_api_keyLa chiave manca, è errata o è stata sostituita.
SoluzioneLa invii nell'header Authorization come Bearer e la copi di nuovo dalla scheda "Integrazione".
403 app_not_liveL'app è in pausa, oppure il suo account non è approvato o attivo.
SoluzioneControlli le sue notifiche. Con user_blocked, non mostri offerte a quell'utente.
429 rate_limitedPiù di 600 richieste in un minuto per questa app.
SoluzioneAttenda i secondi indicati in Retry-After e tenga in cache l'elenco di ogni utente per 1-5 minuti.
Empty offers listÈ una risposta normale: al momento non c'è nulla di disponibile per quell'utente.
SoluzioneMostri uno stato vuoto chiaro e controlli il paese e il dispositivo che invia.
VPN detected on start_urlL'utente usa una VPN, un proxy o una rete cloud quando si apre la pagina dell'offerta.
SoluzioneChieda all'utente di disattivarlo. Le richieste API dal suo server non vengono controllate.
Postback log shows 403 or 404Il suo script ha rifiutato il postback, oppure l'URL è errato.
SoluzioneApra in un browser l'URL presente nel log e controlli il suo codice hash.
Postback log shows a timeoutIl suo script impiega più di 6 secondi a rispondere.
SoluzioneRisponda prima con 200 ed esegua le operazioni lente in background.
Postback log shows 301 or 302Il suo URL reindirizza, ad esempio da http a https.
SoluzioneUsi l'URL finale. I postback non seguono i reindirizzamenti.
Nessun risultato. Veda l'elenco completo nella documentazione oppure ci contatti.
In sintesi
- Endpoint
- GET https://api.moonetix.com/v1/offers
- Autenticazione
- Chiave API Bearer, una per app, solo lato server
- Parametri obbligatori
- user_id, country e device o ua
- Limite di richieste
- Fino a 600 richieste al minuto per ogni app
- Formato
- JSON, con una descrizione OpenAPI
- Prezzo
- Gratuito per i publisher approvati
Altre integrazioni
- Sito webUn link, un iframe o un pulsante Earn flottante. Nessun SDK necessario.
- Android SDKUna schermata offerwall nativa per app Kotlin e Java.
- iOS SDKUn offerwall nativo per Swift, SwiftUI e Objective-C.
- Unity SDKOfferte con ricompensa per giochi Android e iOS, da C#.
- Flutter SDKUn solo plugin Dart per Android e iOS.
- React Native SDKPer app React Native ed Expo, con tipi TypeScript.
- Tutte le integrazioniLi confronti fianco a fianco.
Domande sulla Offers API
Cosa chiedono gli sviluppatori prima di aggiungere la Offers API.
Bloccato su qualcosa? Ci contatti
Quando dovrei usare la Offers API invece dell'offerwall?
Usi il link dell'offerwall per andare live più in fretta. Usi la Offers API se vuole le offerte all'interno del suo sito o della sua app, con il suo design, ad esempio accanto a offerte di altre fonti o nel suo store di ricompense.
Posso chiamare la Offers API da un browser o da un'app mobile?
No. La chiami solo dal suo server, perché la richiesta contiene la sua chiave API. Se la chiave dovesse trapelare, ne crei una nuova nella scheda "Integrazione" e quella vecchia smette subito di funzionare.
Quale paese devo inviare?
Il paese in cui si trova realmente l'utente, come codice di due lettere, ad esempio US. Offerte e ricompense dipendono da questo, e paese e dispositivo vengono verificati di nuovo quando l'utente avvia un'offerta.
Le ricompense sono diverse dall'offerwall?
No. L'API restituisce le stesse offerte del suo offerwall, con le stesse ricompense, e ogni passaggio completato raggiunge il suo server con lo stesso postback firmato.
C'è un limite di richieste?
Sì, fino a 600 richieste al minuto per ogni app. Se mostra spesso l'elenco, lo tenga in cache per breve tempo per ogni utente.
La stessa chiave funziona per altro?
Sì. La chiave API di un'app funziona anche per la Reporting API e per le sessioni degli SDK mobile.
Continui a esplorare.
Trasformi il suo traffico in guadagni.
Crei un account publisher gratuito e guadagni da ogni offerta che i suoi utenti completano sul suo sito web, app, gioco o community.