# YetiPoll developer guide > YetiPoll is a survey wall for apps, games and websites. Users answer paid surveys and are rewarded in the publisher's own currency; the publisher's server is told about every reward. This file is the whole developer documentation in one place. The pages it is built from start at https://yetipoll.com/developers. ## How an integration works 1. The publisher creates an account at https://yetipoll.com and adds an app. Sign-up is instant. 2. The app shows the wall to a signed-in user, passing the app's public key and the publisher's own id for that user. 3. The user completes a survey. YetiPoll calls the publisher's postback URL. 4. The publisher's server verifies the signature and credits the user once. Nothing else is needed. The API is optional: it is for publishers who want to draw their own survey list or reconcile. ## Rules to follow when writing an integration - The secret key stays on the server. Never put it in a web page, a mobile app or a game client. Only the public key goes there. - Start with the sandbox keys (`yp_test_…`). Going live is swapping the keys, nothing else. - Credit users from the postback, never from the client. The wall and the SDKs do not report rewards to the app on purpose. - Handle each `transaction_id` + `status` pair once. A reversal carries the same `transaction_id` as the completion it cancels, so deduplicating on the id alone would ignore every reversal. - When `test` is `1`, run the code but do not credit a real balance. - A user id is 1 to 128 characters from letters, digits and `_ . @ : -`. Use a stable account id, not an email address. ## Keys Each app has four keys. The key decides the mode. | Key | Looks like | Where it goes | |---|---|---| | Sandbox public | `yp_test_pk_…` | In pages and apps while building. Practice surveys only. | | Sandbox secret | `yp_test_sk_…` | On the server: verifies sandbox postbacks, opens the API in sandbox. | | Live public | `yp_live_pk_…` | In pages and apps in production. | | Live secret | `yp_live_sk_…` | On the server only. | A secret key can be replaced from the app page in the dashboard. The old one stops working at once. ## Showing the wall ### Web: the script ```html
``` | Attribute | Meaning | |---|---| | `data-app` | The public key. Required. | | `data-user` | The publisher's id for the signed-in user. Required. | | `data-signature` | Signature of the user id, when the app requires signed links. | | `data-target` | CSS selector of the element to render into. Without it the wall is placed after the script tag. | | `data-display` | `inline` (default) or `button`. | | `data-label` | Text of the button. The button has the class `yetipoll-button` and no styling of its own. | For single-page apps, load the script once without data attributes and start it when the user is known: ```js YetiPoll.init({ app: "yp_test_pk_your_key", user: currentUser.id, target: "#surveys" }); YetiPoll.on("survey_opened", function () { /* the user started a survey */ }); ``` `YetiPoll.open()` and `YetiPoll.close()` show the wall as an overlay from your own button. Events: `ready`, `survey_opened`, `close`. A site with a Content Security Policy allows `https://yetipoll.com` in `script-src` and `frame-src`. ### Anywhere: the wall as a page ```html ``` | Parameter | Meaning | |---|---| | `app` | The public key. Required. | | `user` | The publisher's id for the user. Required. | | `sig` | Signature of the user id. Required when the app has "Require signed wall links" on. | | `embed` | `1` hides the wall's own heading. | The wall posts its height to the parent page whenever it changes: ```js window.addEventListener("message", function (event) { if (event.origin !== "https://yetipoll.com") return; if (event.data && event.data.source === "yetipoll" && event.data.type === "height") { document.querySelector("iframe").style.height = event.data.height + "px"; } }); ``` The wall sets no cookies and needs no session. Its colour, light or dark background, heading and corner style are set per app in the dashboard. ### Mobile and game engines: the SDKs Each SDK is one source file to add to the project. It opens the wall for the signed-in user inside the app and refreshes the list when the user comes back. | Platform | File | |---|---| | Web script | https://yetipoll.com/sdk/v1/yetipoll.js | | Android (Kotlin) | https://yetipoll.com/sdk/android/YetiPoll.kt | | iOS (Swift) | https://yetipoll.com/sdk/ios/YetiPoll.swift | | Unity (C#) | https://yetipoll.com/sdk/unity/YetiPoll.cs | | Flutter (Dart) | https://yetipoll.com/sdk/flutter/yetipoll.dart | | React Native | https://yetipoll.com/sdk/react-native/YetiPoll.tsx | | React (web) | https://yetipoll.com/sdk/react/YetiPoll.jsx | ```kotlin YetiPoll.open(context, appKey = "yp_test_pk_your_key", userId = currentUser.id) ``` ```swift YetiPoll.present(from: self, appKey: "yp_test_pk_your_key", userId: currentUser.id) ``` ```csharp YetiPoll.Open("yp_test_pk_your_key", playerId); ``` Any other platform that can show a web page loads `https://yetipoll.com/wall?app=…&user=…` in a web view. ### Signing wall links By default anyone who knows a user id could open that user's wall. Rewards still only reach users through the publisher's server, but for production turn on "Require signed wall links" in the app settings. The wall then only opens with a signature the server made: `sig = HMAC-SHA256(user id, secret key)`, as lowercase hex. ```php $sig = hash_hmac("sha256", $userId, $secretKey); ``` ```js const sig = crypto.createHmac("sha256", secretKey).update(userId).digest("hex"); ``` ```python sig = hmac.new(secret_key.encode(), user_id.encode(), hashlib.sha256).hexdigest() ``` Or ask the API for a ready-made signed address: `GET /api/v1/wall-url`. ## Postbacks: receiving rewards A postback is an HTTP GET from YetiPoll to the publisher's server, sent when a user completes a survey, is screened out, or when a completion is taken back. The URL is set per app. Placeholders are replaced with URL-encoded values: ``` https://your-server.example/yetipoll?user={user_id}&tx={transaction_id}&reward={reward}&status={status}&test={test}&sig={signature} ``` A URL without any placeholder gets every value appended as a query parameter under the names below. | Placeholder | Value | |---|---| | `{user_id}` | Your own id for the user | | `{transaction_id}` | Our id for the completion. A reversal reuses it | | `{reward}` | Amount in your currency. Negative on a reversal | | `{payout_usd}` | What the completion earned you, in US dollars | | `{currency}` | The name of your reward currency | | `{status}` | completed, screenout or reversed | | `{type}` | complete, screenout or bonus | | `{country}` | Two-letter country of the user, when known | | `{test}` | 1 for sandbox and test postbacks, otherwise 0 | | `{timestamp}` | Unix time the postback was built | | `{signature}` | HMAC-SHA256 of user_id:transaction_id:reward:status | ### The three statuses | `status` | Meaning | `reward` | |---|---|---| | `completed` | The user finished a survey. Credit them. | Positive | | `screenout` | The user did not qualify. Usually nothing to credit. | 0, or a small consolation amount | | `reversed` | An earlier completion was taken back after a quality check. Deduct it. | Negative: the original amount, negated | ### What the handler does 1. Verify the signature. Reject anything that does not match. 2. If this `transaction_id` + `status` pair was handled before, answer 200 and stop. 3. Unless `test` is `1`, add `reward` to the user's balance (it is negative on a reversal). 4. Remember the pair. Answer with any 2xx status; the body does not matter. ### Verifying the signature `signature = HMAC-SHA256("user_id:transaction_id:reward:status", secret key)`, lowercase hex. Use the values exactly as they arrive, without reformatting the reward, and the secret key of the mode the postback belongs to (the sandbox key for sandbox postbacks). ```php { const { user, tx, reward, status, test, sig = "" } = req.query; const expected = crypto .createHmac("sha256", process.env.YETIPOLL_SECRET) .update(`${user}:${tx}:${reward}:${status}`) .digest("hex"); const ok = sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); if (!ok) return res.sendStatus(403); if (await alreadyHandled(tx, status)) return res.sendStatus(200); if (test !== "1") await addToBalance(user, Number(reward)); await remember(tx, status); res.sendStatus(200); }); ``` ```python # Python (Flask) import hashlib, hmac, os from flask import request @app.get("/yetipoll") def yetipoll(): q = request.args payload = f"{q['user']}:{q['tx']}:{q['reward']}:{q['status']}" expected = hmac.new(os.environ["YETIPOLL_SECRET"].encode(), payload.encode(), hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, q.get("sig", "")): return "", 403 if already_handled(q["tx"], q["status"]): return "", 200 if q.get("test", "0") != "1": add_to_balance(q["user"], float(q["reward"])) remember(q["tx"], q["status"]) return "", 200 ``` ### Retries If the server does not answer with a 2xx status within a few seconds, the postback is sent again with growing pauses, from about a minute up to a day, for several attempts. Then it is marked failed and can be resent from the postback log in the dashboard. The same data can always be read from `GET /api/v1/conversions`. ### Testing The app page in the dashboard sends a test completion and a test reversal. Both are signed with the secret key of the mode being viewed and carry `test=1`. ## Sandbox and live | | Sandbox | Live | |---|---|---| | Keys | `yp_test_pk_…`, `yp_test_sk_…` | `yp_live_pk_…`, `yp_live_sk_…` | | Surveys | Practice surveys that end the way the tester chooses | Real surveys, matched to each user | | Earnings | None | Added to the publisher's balance and invoiced monthly | | Postbacks | Same URL, `test=1`, signed with the sandbox secret key | `test=0`, signed with the live secret key | | API | Sandbox data only | Live data only | A full test run: open the wall with the sandbox public key as any user id, open a practice survey, choose "Complete the survey" (a `completed` postback arrives), then "Now reverse it" (a `reversed` postback with the same `transaction_id` and the reward negated). Open another and choose "Screen out". Before live traffic: - The integration uses the live public key. - The postback handler verifies with the live secret key, deducts on `reversed`, and does not credit real users when `test=1`. - "Require signed wall links" is on and the server signs user ids. ## API reference For the publisher's server only. Base URL `https://yetipoll.com/api/v1`. Machine-readable description: https://yetipoll.com/openapi.json - Authentication: `Authorization: Bearer