iOS 오퍼월 SDK. Swift, SwiftUI, Objective-C 지원.
Swift 패키지 하나로 iPhone 및 iPad 앱에서 Moonetix 오퍼월을 여세요. UIKit과 WebKit만 사용하고, 서드파티 의존성이 없으며, 개인정보 매니페스트가 포함되어 있습니다.
- 13+iOS 및 iPadOS
- 2.0.1현재 버전
- 0서드파티 의존성
import MoonetixOfferwall
Moonetix.configure(appId: "YOUR_APP_ID")
// When the user taps Earn
Moonetix.open(token: token)네 단계로 시작하세요.
코드를 복사하고, 자리 표시자를 대시보드의 오퍼월, 해당 오퍼월, 연동에 있는 값으로 바꾼 다음 출시 전에 테스트하세요.
-
SDK 설치
Xcode에서 File, Add Package Dependencies로 패키지를 추가하거나 CocoaPods를 사용하세요. xcframework를 내려받아 직접 포함할 수도 있습니다. Xcode 16 이상으로 빌드하세요.
Package.swiftdependencies: [ .package(url: "https://moonetix.com/ios/moonetix-ios.git", from: "2.0.1"), ], targets: [ .target(name: "MyApp", dependencies: [ .product(name: "MoonetixOfferwall", package: "moonetix-ios"), ]), ]Podfilepod 'MoonetixOfferwall', :podspec => 'https://moonetix.com/ios/2.0.1/MoonetixOfferwall.podspec' -
서버에 토큰 엔드포인트 추가
앱은 API 키를 절대 갖지 않습니다. 사용자가 Earn을 탭하면 앱이 서버에 세션을 요청하고, 서버는 로그인한 사용자를 위한 일회용 토큰을 Moonetix에 요청합니다. 토큰은 10분 동안 한 번만 사용할 수 있습니다.
session.php<?php // POST /api/moonetix/session: a fresh token for the signed-in user $user = current_user(); if (!$user) { http_response_code(401); exit; } $key = getenv('MOONETIX_API_KEY'); $ch = curl_init('https://api.moonetix.com/v1/session'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query(['user_id' => (string)$user->id]), CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key], ]); $data = json_decode((string)curl_exec($ch), true); $code = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE); header('Content-Type: application/json'); if ($code === 201 && !empty($data['token'])) { echo json_encode(['token' => $data['token']]); exit; } http_response_code($code === 403 ? 403 : 503); echo json_encode(['error' => 'offerwall_unavailable']);session.js// POST /api/moonetix/session: a fresh token for the signed-in user app.post('/api/moonetix/session', requireLogin, async (req, res) => { const r = await fetch('https://api.moonetix.com/v1/session', { method: 'POST', headers: { Authorization: `Bearer ${process.env.MOONETIX_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ user_id: String(req.user.id) }), signal: AbortSignal.timeout(10000), }); const data = await r.json().catch(() => ({})); if (r.status === 201 && data.token) { return res.json({ token: data.token }); } const status = r.status === 403 ? 403 : 503; res.status(status).json({ error: 'offerwall_unavailable' }); });session.py# POST /api/moonetix/session: a fresh token for the signed-in user @app.post("/api/moonetix/session") @login_required def moonetix_session(): key = os.environ["MOONETIX_API_KEY"] r = requests.post( "https://api.moonetix.com/v1/session", data={"user_id": str(current_user.id)}, headers={"Authorization": f"Bearer {key}"}, timeout=10, ) data = r.json() if r.status_code == 201 and data.get("token"): return {"token": data["token"]} status = 403 if r.status_code == 403 else 503 return {"error": "offerwall_unavailable"}, status -
오퍼월 열기
대시보드의 App ID로 한 번 설정한 다음, 새 토큰으로 오퍼월을 여세요. view controller를 지정하지 않으면 SDK가 앱의 최상위 화면에서 띄우므로 SwiftUI에서도 작동합니다.
EarnViewController.swiftMoonetix.configure(appId: "YOUR_APP_ID") Moonetix.onClosed = { [weak self] in self?.refreshBalance() } Moonetix.onError = { error in print(error.code.name, error.message) } Moonetix.open(token: token, from: self)EarnButton.swiftButton("Earn coins") { Task { let token = try await api.fetchMoonetixToken() Moonetix.open(token: token) } }EarnViewController.m@import MoonetixOfferwall; [Moonetix configureWithAppId:@"YOUR_APP_ID"]; [Moonetix openWithToken:token from:self options:nil]; -
postback으로 리워드 적립
모든 리워드는 서명된 postback으로 서버에 전달됩니다. 해시를 확인하고, 거래 ID당 한 번만 리워드를 추가하고, 이후 postback이 취소를 알리면 회수하세요. 실패한 postback은 최대 5회까지 재시도됩니다.
대시보드, 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
Travel Town레벨 15 달성+1,500
WPS Office설치 후 실행+2,000
Bus Escape레벨 20 달성+450
CapCutSign up in the app+800
사용자에게 보이는 화면
앱 위에 뜨는 네이티브 화면입니다. 자체 제목과 색상, 자체 화폐를 사용하며 모든 리워드는 postback으로 확인됩니다.
SDK가 대신 처리하는 것
- 오퍼가 알맞은 곳에서 열립니다
App Store로 연결되는 오퍼는 스토어 앱에서, 다른 사이트는 브라우저에서 열리므로 설치가 정확히 추적됩니다.
- 앱 안에 키 없음
앱에는 App ID만 들어갑니다. 세션은 서버에서 만들어지고 한 번만 사용할 수 있으므로 누구도 다른 사용자로 오퍼월을 열 수 없습니다.
- 외부 이동이 차단된 전용 화면
그 안에서는 오퍼월 페이지만 로드되며, 앱으로 연결되는 JavaScript 브리지는 없습니다.
- 네이티브 내비게이션
닫기 버튼을 누르면 앱으로 돌아가고, 왼쪽 가장자리에서 스와이프하면 오퍼월 안에서 뒤로 이동하며, 백그라운드에서 돌아오면 사용자가 보던 위치에서 다시 시작됩니다.
- 기본 접근성 지원
라이트 모드와 다크 모드, 큰 글꼴 크기, VoiceOver를 별도 설정 없이 지원합니다.
- 개인정보 매니페스트 포함
SDK에는 개인정보 매니페스트가 포함되어 있으며, 기기 핑거프린팅을 하지 않고 광고 식별자도 사용하지 않습니다.
테스트한 다음 출시하세요.
실제 사용자가 오퍼월을 보기 전에 확인해야 할 모든 것을 대시보드에 내장된 도구로 점검하세요.
테스트 사용자로 열기
연동 탭의 연동 상태에서 owner-test 사용자로 오퍼월을 여세요. 테스트 방문은 사용자로 집계되지 않습니다.
실제 기기에서 실행하기
Android 또는 iOS용으로 빌드하고, Earn 버튼에서 매번 새 토큰으로 오퍼월을 여세요.
테스트 postback 보내기
사용자, 상태, 지급액을 선택하고 서버가 어떻게 응답했는지 응답 코드와 시간까지 정확히 확인하세요. 테스트 거래 ID는 test_로 시작합니다.
일반 연결에서 테스트
VPN, 프록시, Tor, 클라우드 네트워크는 차단되므로, 오퍼가 운영되는 국가에서 가정용 Wi-Fi나 모바일 데이터로 테스트하세요.
출시 체크리스트
11개 중 0개 준비됨
출시 준비 완료. 진행 상황은 이 브라우저에 저장됩니다.
자주 발생하는 오류, 빠르게 해결.
iOS SDK를 연동하는 동안 볼 수 있는 오류와 그 원인, 해결 방법.
INVALID_APP_IDinit에 전달한 값이 App ID가 아닙니다. 여기에 API 키를 넣는 것이 가장 흔한 실수입니다.
해결 방법연동 탭에서 24자리 App ID를 다시 복사하세요.
INVALID_TOKEN앱이 토큰이 아닌 다른 값을 전달했거나, 다른 앱의 API 키로 만든 토큰을 전달했습니다.
해결 방법sst_로 시작하는 token 필드만 전달하고, 같은 앱의 App ID와 API 키를 사용하세요.
TOKEN_EXPIRED_OR_USED토큰이 10분보다 오래되었거나 이미 사용되었습니다. 예를 들어 이전 탭에서 받아 둔 토큰일 수 있습니다.
해결 방법사용자가 Earn을 탭하는 바로 그 순간에, 열 때마다 새 토큰을 만드세요.
NOT_INITIALIZEDinit 전에 open이 호출되었습니다.
해결 방법앱이 시작될 때 Moonetix.configure를 호출하세요.
UNKNOWN오퍼월이 이미 열려 있거나, 화면을 띄울 view controller가 화면에 없었습니다.
해결 방법한 번에 하나만 열고, open(token:from:)에 화면에 보이는 view controller를 전달하세요.
Delegate is never calledMoonetix.delegate는 약한 참조이므로 객체가 이미 해제되었습니다.
해결 방법delegate에 대한 강한 참조를 유지하거나 클로저를 사용하세요.
403 from /v1/sessionapp_not_live는 앱이 일시 중지되었거나 계정이 활성 상태가 아니라는 뜻입니다. user_blocked는 저희가 이 사용자를 차단했다는 뜻입니다.
해결 방법오퍼월을 표시하지 마세요. app_not_live인 경우 알림을 확인하세요.
VPN or Proxy detected기기가 VPN, 프록시 또는 클라우드 네트워크를 사용하고 있어 오퍼를 추적할 수 없습니다.
해결 방법오퍼가 운영되는 국가에서 일반 가정용 또는 모바일 연결로 테스트하세요.
Postback log shows 403 or 404스크립트가 postback을 거부했거나 URL이 잘못되었습니다.
해결 방법로그에 있는 URL을 브라우저에서 열고 해시 코드를 확인하세요.
Postback log shows a timeout스크립트가 응답하는 데 6초보다 오래 걸립니다.
해결 방법먼저 200으로 응답하고, 오래 걸리는 작업은 백그라운드에서 실행하세요.
Postback log shows 301 or 302URL이 리디렉션됩니다. 예를 들어 http에서 https로 이동합니다.
해결 방법최종 URL을 사용하세요. Postback은 리디렉션을 따라가지 않습니다.
일치하는 항목이 없습니다. 문서에서 전체 목록을 보거나 문의해 주세요.
한눈에 보기
- 최소 버전
- iOS 13, iPhone 및 iPad, Xcode 16 이상으로 빌드
- 언어
- Swift, SwiftUI, Objective-C
- 설치
- Swift Package Manager, CocoaPods 또는 xcframework
- 의존성
- UIKit과 WebKit만 사용
- 개인정보
- 개인정보 매니페스트 포함, 광고 식별자 미사용
- 가격
- 승인된 퍼블리셔는 무료
다른 연동 방식
- 웹사이트링크, iframe 또는 플로팅 Earn 버튼. SDK가 필요 없습니다.
- Offers API오퍼를 JSON으로 받아 자체 디자인으로 표시하세요.
- Android SDKKotlin 및 Java 앱용 네이티브 오퍼월 화면.
- Unity SDKC#으로 구현하는 Android 및 iOS 게임용 리워드형 오퍼.
- Flutter SDKAndroid와 iOS를 모두 지원하는 Dart 플러그인 하나.
- React Native SDKTypeScript 타입이 포함된 React Native 및 Expo 앱용 패키지.
- 모든 연동 방식나란히 비교해 보세요.
Moonetix SDK는 어떤 iOS 버전을 지원하나요?
iPhone 및 iPad의 iOS 13 이상, Xcode 16 이상으로 빌드. SDK는 UIKit과 WebKit만 사용하며 서드파티 의존성이 없습니다.
SwiftUI에서 사용할 수 있나요?
네. view controller 없이 Moonetix.open(token:)을 호출하면 SDK가 앱의 최상위 화면에서 띄우므로 SwiftUI 버튼에서도 작동합니다.
어떻게 설치하나요?
https://moonetix.com/ios/moonetix-ios.git을 사용하는 Swift Package Manager, 제공되는 podspec을 사용하는 CocoaPods, 또는 xcframework를 직접 포함하는 방법이 있습니다.
App Store 개인정보 세부사항에는 무엇을 신고하나요?
User ID, Device ID, Coarse Location, Product Interaction. 모두 사용자와 연결되고 추적에는 사용되지 않으며, 용도는 App Functionality입니다. SDK의 개인정보 매니페스트에도 같은 데이터가 나와 있습니다.
오퍼월이 App Store 심사 규칙에 어긋나나요?
Apple에는 사용자에게 리워드를 주는 앱에 관한 규칙이 있습니다. Academy에는 이 규칙을 지키면서 iOS 앱에서 오퍼월을 운영하는 방법과 리워드 문구 작성법을 다룬 가이드가 있습니다.
사용자는 어떻게 리워드를 받나요?
서버는 리워드마다 서명된 postback을 받고 사용자에게 적립합니다. 앱 이벤트는 기기에서 위조될 수 있으므로 절대 이벤트로 적립하지 마세요.