Android Quickstart (WebView)

You will: pass your signed-in user's id to your server, host one small web page (the bootstrap), show it in a WKWebView, listen for three events, and credit the user from a webhook. No SDK to install — the intelligence is in the web page; the app is a careful container.

How it fits together

Your appKnow your user
After sign-in, your app has a stable user id. That id — never an email — is who earns.
Your serverMint a token
Your server signs a 10-minute launch token for that user with your secret key.
Bootstrap pageStart the widget
A page on your server loads the widget with that token.
WKWebViewShow and listen
The webview displays the page; your app hears earn, height, and token-expired events.
Your serverCredit from the webhook
AIRewards POSTs reward.earned to your server. That — not the app event — is when you credit.

Step 1 · Pass the end-user id

Pick the id you already use for the signed-in user in your own system (for example user_88123). Rules: stable per user, at most 128 characters, never an email or a name. Caps, reporting, and the webhook all key on it, so changing a user's id later splits their history.

Step 2 · Mint the token on your server

Add one endpoint to your server, for example GET /airewards/token?user_id=…, that returns the signed launch token from the launch-token recipe (Node, Python, and PHP samples there). Authenticate the request the same way you authenticate the rest of your app — the token proves your server vouched for this user. Never put the secret key in the app.

Step 3 · Host the bootstrap page

Serve this page from your server (for example at /airewards/earn?user_id=…). It fetches the token and starts the widget. This exact page also opens in a desktop browser, which is your best debugging tool.

<!DOCTYPE html>
<html><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Earn</title></head>
<body>
<div id="airewards"></div>
<script src="https://airewards.b-cdn.net/loader@1.js" async></script>
<script>
  // This page is served by YOUR server. The user id arrives in the page
  // URL (put it there only after your user is signed in — never trust a
  // user id typed into a client-side form).
  var userId = new URLSearchParams(location.search).get('user_id');
  function initWidget() {
    fetch('/airewards/token?user_id=' + encodeURIComponent(userId), { credentials: 'same-origin' })
      .then(function (r) { return r.json(); })
      .then(function (data) {
        window.AIRewards.init({
          container: '#airewards',
          launchToken: data.airewardsToken,   // signed on your server, see /docs#token
          heightMode: 'auto',
          onEarn: function () { /* UI hint only — credit comes from the webhook */ },
          onTokenExpired: function () { location.reload(); }
        });
      });
  }
  if (window.AIRewards) initWidget();
  else window.addEventListener('airewards:ready', initWidget);
</script>
</body></html>

New chat and chat history from native code: evaluate AIRewards.newChat(), AIRewards.getHistory(), or AIRewards.openConversation(id) in this page. Per-platform snippets are in New chat & history.

Put the user id in the bootstrap URL only from a signed-in server session. Anyone who can change that id can earn as that user in test mode; live mode is protected by the token, but keep the habit clean.

Step 4 · Show it in a WebView

import android.webkit.JavascriptInterface
import android.webkit.WebView
import android.webkit.WebViewClient

class EarnActivity : AppCompatActivity() {
    private lateinit var webView: WebView

    // The widget calls AIRewardsBridge.postMessage(json) — the name must match exactly.
    inner class Bridge {
        @JavascriptInterface
        fun postMessage(json: String) {
            val msg = JSONObject(json)
            if (msg.optString("source") != "airewards") return
            runOnUiThread {
                when (msg.optString("type")) {
                    "reward.earned" -> refreshBalanceFromYourBackend() // UI hint only
                    "airewards:height" -> resizeWebView(msg.optInt("height"))
                    "airewards:token-expired" -> webView.reload()      // fresh token
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        webView = WebView(this)
        setContentView(webView)
        webView.settings.javaScriptEnabled = true   // required
        webView.settings.domStorageEnabled = true   // required
        webView.addJavascriptInterface(Bridge(), "AIRewardsBridge")
        webView.webViewClient = WebViewClient()
        // Your hosted bootstrap page, with your signed-in user's id.
        webView.loadUrl("https://your-server.example/airewards/earn?user_id=user_88123")
    }

    private fun resizeWebView(heightPx: Int) { /* update layout height for inline use */ }
    private fun refreshBalanceFromYourBackend() { /* re-read the credited balance */ }
}

Three platform facts that matter: JavaScript and DOM storage are off by default and must be enabled or the widget cannot run; the interface name must be exactly "AIRewardsBridge" because that is who the widget posts JSON strings to; and a JavaScript interface is powerful — only ever load your own bootstrap page in a webview that has one.

Step 5 · Embed elegantly: fullscreen or inline

Fullscreen (simplest, recommended first): give the webview the whole screen and let the widget scroll internally. Nothing else to manage.

Inline in a scrolling page: the bootstrap uses heightMode: 'auto', and the widget reports its content height with airewards:height events. Resize the webview to that height (disable the webview's own scrolling) so your page scrolls as one. Do not put an auto-height widget inside a fixed-height clipped container — growing content will be cut off.

Step 6 · Set the webhook and credit the user

In Dashboard → Webhook, save your HTTPS endpoint. When a user earns, AIRewards POSTs reward.earned there, signed with your webhook secret. Verify the signature (copy-paste verifiers in the main guide), credit that user_id in your own currency, and dedupe on event_id — retries reuse it. The app event in Step 4 only refreshes your UI; if your webhook is down, nobody is credited, and we email the account owners when that happens.

Before you ship

Token endpoint requires your app's normal authentication; the secret key exists only on the server.
Bootstrap page opens and completes a test duel in a desktop browser.
JavaScript interface registered with the exact name "AIRewardsBridge"; earn event refreshes the balance display.
Webhook verifies signatures, dedupes on event_id, and credits only from the webhook.
Test event from the dashboard Webhook page lands and credits a test user.

Questions: hello@jutera.com · React Native guide →