Offers API. Thiết kế của bạn, offer của chúng tôi.
Lấy danh sách offer cho từng người dùng dưới dạng JSON, với hình ảnh, các bước và phần thưởng đã quy đổi sang đơn vị tiền tệ của bạn, rồi hiển thị chúng trong thẻ của riêng bạn, cạnh nội dung của bạn. Phần thưởng đến qua postback, giống như với offerwall.
- JSONREST qua HTTPS
- 600Số yêu cầu mỗi phút
- OpenAPICó kèm đặc tả
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"Triển khai trong ba bước.
Sao chép mã, thay các giá trị giữ chỗ bằng giá trị từ bảng điều khiển của bạn trong "Offerwall", offerwall của bạn, "Tích hợp", và thử nghiệm trước khi ra mắt.
-
Yêu cầu offer cho một người dùng
Gọi API từ máy chủ của bạn với khóa API của ứng dụng, ID người dùng, quốc gia người dùng đang ở, và thiết bị hoặc user agent của họ. Danh sách sẽ bỏ qua các offer mà người dùng đã hoàn thành hoặc chưa thể làm lại.
Terminalcurl -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() -
Hiển thị theo thiết kế của riêng bạn
Mỗi offer đi kèm tiêu đề, hình ảnh, các bước và phần thưởng theo đơn vị tiền tệ của bạn. Hãy hiển thị chúng theo cách bạn muốn, và đưa người dùng tới start_url của offer khi họ chọn. Trang offer mở trên Moonetix và từ đó dẫn họ tới nhà quảng cáo.
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, })); } -
Cộng thưởng bằng postback
Mọi phần thưởng tới máy chủ của bạn dưới dạng postback có chữ ký. Hãy kiểm tra mã hash, cộng thưởng một lần cho mỗi ID giao dịch, và lấy lại nếu một postback sau đó thu hồi nó. Postback thất bại được gửi lại tối đa 5 lần.
Bảng điều khiển, tab "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/..."
}
- Tạo tài khoản+325
- Đạt cấp 10+650
Từ JSON đến thiết kế của bạn
Mỗi offer đến sẵn sàng để hiển thị, với các bước và phần thưởng đã quy đổi sang đơn vị tiền tệ của bạn.
API mang lại cho bạn những gì
- Offer cho mỗi người dùng
Các offer phù hợp với quốc gia và thiết bị bạn gửi, và những offer người dùng đã hoàn thành sẽ bị loại bỏ.
- Phần thưởng theo đơn vị tiền tệ của bạn
Mọi phần thưởng đều đã được tính sẵn theo tỷ lệ quy đổi, tỷ lệ chia cho người dùng, cách làm tròn và mọi khoản thưởng thêm đang chạy.
- Các bước và hình ảnh
Offer nhiều bước liệt kê từng bước với phần thưởng riêng, để bạn hiển thị chính xác bước nào được trả tiền.
- Sub ID
Gửi tối đa năm giá trị của riêng bạn. Chúng được thêm vào mọi start_url và trả về trong postback.
- Offer đã ẩn vẫn bị ẩn
Offer bạn ẩn trên trang "Offer" cũng bị loại khỏi API, nên API khớp với offerwall của bạn.
- Đặc tả OpenAPI
File openapi.json mà máy có thể đọc mô tả mọi trường, sẵn sàng cho các công cụ tạo mã và agent lập trình AI.
Thử nghiệm, rồi ra mắt.
Mọi thứ bạn cần kiểm tra trước khi người dùng thật thấy offerwall của bạn, với các công cụ có sẵn trong bảng điều khiển.
Mở với tư cách người dùng thử nghiệm
Trong "Trạng thái tích hợp" ở tab "Tích hợp", hãy mở offerwall của bạn với tư cách người dùng owner-test. Lượt truy cập thử nghiệm không được tính là người dùng.
Gọi API bằng curl
Yêu cầu danh sách cho một ID người dùng thử nghiệm và một quốc gia có offer đang chạy, rồi mở một start_url trong trình duyệt.
Gửi postback thử nghiệm
Chọn người dùng, trạng thái và mức thanh toán, rồi xem chính xác máy chủ của bạn đã trả lời gì, kèm mã phản hồi và thời gian. ID giao dịch thử nghiệm bắt đầu bằng test_.
Thử nghiệm từ một kết nối bình thường
VPN, proxy, Tor và mạng đám mây đều bị chặn, vì vậy hãy thử nghiệm qua Wi-Fi gia đình hoặc dữ liệu di động, ở quốc gia có offer đang chạy.
Danh sách kiểm tra trước khi ra mắt
0 / 10 mục đã sẵn sàng
Sẵn sàng ra mắt. Tiến độ của bạn được lưu trong trình duyệt này.
Lỗi thường gặp, khắc phục nhanh.
Những lỗi bạn có thể gặp khi tích hợp Offers API, nguyên nhân và cách khắc phục.
400 invalid_countryThiếu hoặc sai một tham số: invalid_user_id, invalid_country hoặc invalid_device.
Khắc phụcSửa tham số được nêu trong mã lỗi.
401 invalid_api_keyKhóa bị thiếu, sai hoặc đã được thay thế.
Khắc phụcGửi nó trong header Authorization dưới dạng Bearer, và sao chép lại từ tab "Tích hợp".
403 app_not_liveỨng dụng đang tạm dừng, hoặc tài khoản của bạn chưa được duyệt hoặc chưa hoạt động.
Khắc phụcKiểm tra thông báo của bạn. Với user_blocked, đừng hiển thị offer cho người dùng đó.
429 rate_limitedHơn 600 yêu cầu trong một phút cho ứng dụng này.
Khắc phụcChờ đủ số giây trong Retry-After, và lưu cache danh sách của từng người dùng trong 1 đến 5 phút.
Empty offers listĐây là phản hồi bình thường: hiện chưa có offer nào cho người dùng đó.
Khắc phụcHiển thị một trạng thái trống thân thiện, và kiểm tra quốc gia cùng thiết bị bạn gửi.
VPN detected on start_urlNgười dùng đang dùng VPN, proxy hoặc mạng đám mây khi trang offer mở ra.
Khắc phụcĐề nghị người dùng tắt nó đi. Các yêu cầu API từ máy chủ của bạn không bị kiểm tra.
Postback log shows 403 or 404Script của bạn đã từ chối postback, hoặc URL bị sai.
Khắc phụcMở URL trong log bằng trình duyệt và kiểm tra mã hash của bạn.
Postback log shows a timeoutScript của bạn mất hơn 6 giây để trả lời.
Khắc phụcTrả lời 200 trước, rồi chạy các tác vụ chậm ở chế độ nền.
Postback log shows 301 or 302URL của bạn có chuyển hướng, ví dụ từ http sang https.
Khắc phụcDùng URL cuối cùng. Postback không đi theo chuyển hướng.
Không tìm thấy. Xem danh sách đầy đủ trong tài liệu hoặc liên hệ với chúng tôi.
Tổng quan nhanh
- Endpoint
- GET https://api.moonetix.com/v1/offers
- Xác thực
- Khóa API dạng Bearer, mỗi ứng dụng một khóa, chỉ dùng phía máy chủ
- Tham số bắt buộc
- user_id, country và device hoặc ua
- Giới hạn tần suất
- Tối đa 600 yêu cầu mỗi phút cho mỗi ứng dụng
- Định dạng
- JSON, kèm mô tả OpenAPI
- Giá
- Miễn phí cho publisher đã được duyệt
Cách tích hợp khác
- Trang webMột liên kết, một iframe hoặc một nút Earn nổi. Không cần SDK.
- Android SDKMàn hình offerwall native cho ứng dụng Kotlin và Java.
- iOS SDKOfferwall native cho Swift, SwiftUI và Objective-C.
- Unity SDKOffer có thưởng cho game Android và iOS, từ C#.
- Flutter SDKMột plugin Dart cho Android và iOS.
- React Native SDKDành cho ứng dụng React Native và Expo, có kèm kiểu TypeScript.
- Tất cả tích hợpSo sánh song song.
Câu hỏi về Offers API
Những điều nhà phát triển thường hỏi trước khi thêm Offers API.
Gặp vướng mắc? Liên hệ với chúng tôi
Khi nào tôi nên dùng Offers API thay vì offerwall?
Dùng liên kết offerwall để triển khai nhanh nhất. Dùng Offers API khi bạn muốn offer nằm trong trang web hoặc ứng dụng của riêng mình, theo thiết kế của riêng bạn, ví dụ cạnh offer từ các nguồn khác hoặc trong cửa hàng phần thưởng của bạn.
Tôi có thể gọi Offers API từ trình duyệt hoặc ứng dụng di động không?
Không. Chỉ gọi từ máy chủ của bạn, vì yêu cầu mang theo khóa API. Nếu khóa bị lộ, hãy tạo khóa mới trong tab "Tích hợp" và khóa cũ sẽ ngừng hoạt động ngay lập tức.
Tôi nên gửi quốc gia nào?
Quốc gia mà người dùng thực sự đang ở, dưới dạng mã hai chữ cái như US. Offer và phần thưởng phụ thuộc vào nó, và quốc gia cùng thiết bị được kiểm tra lại khi người dùng bắt đầu một offer.
Phần thưởng có khác với offerwall không?
Không. API trả về các offer giống như offerwall của bạn, với cùng phần thưởng, và mỗi bước hoàn thành đều tới máy chủ của bạn qua cùng một postback có chữ ký.
Có giới hạn tần suất gọi không?
Có, tối đa 600 yêu cầu mỗi phút cho mỗi ứng dụng. Hãy lưu cache danh sách của từng người dùng trong thời gian ngắn nếu bạn hiển thị nó thường xuyên.
Khóa này có dùng được cho việc khác không?
Có. Khóa API của một ứng dụng cũng dùng được cho Reporting API và cho phiên SDK di động.
Biến lưu lượng truy cập thành thu nhập.
Tạo tài khoản publisher miễn phí và kiếm tiền từ mỗi offer mà người dùng hoàn thành trên trang web, ứng dụng, game hoặc cộng đồng của bạn.