Integrate your mobile app

0. Networking prerequisites

Every public endpoint is HTTPS with a valid certificate, so no App Transport Security exception and no cleartextTrafficPermitted config are needed. If an older build of your app still carries either, remove it — shipping a cleartext exception you do not need is a finding waiting to happen in app review. Two things to get right instead:

Read the base URLs from config

The hostnames encode the server IP (54-237-170-237.sslip.io). Keep them in an environment/remote-config file so an infrastructure move does not require a new release — see Network status.

Give chain calls their own client

Do not route chain traffic through the client that carries your product’s auth token. A 401 handler that force-signs-out has no business firing because a blockchain node was slow. Use a separate fetch wrapper with its own timeout (12s is what the reference app uses).

1. Register the device on launch

await fetch("https://api.54-237-170-237.sslip.io/api/mobile/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    address: wallet.address,
    deviceId,
    os,
    model,
    appVersion: pkg.version,
    region,
    hardwareConcurrency: navigator.hardwareConcurrency,
    deviceMemory: (navigator as any).deviceMemory,
  }),
});

2. Heartbeat loop

Every 30–60s while the app is foreground + online:

setInterval(() => {
  fetch("https://api.54-237-170-237.sslip.io/api/mobile/heartbeat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      deviceId,
      address: wallet.address,
      battery: await Battery.level(),
      batteryCharging: await Battery.charging(),
      online: true,
      connectionType: NetInfo.type,
    }),
  });
}, 45_000);

3. Submit engagement on user action

async function recordEngagement(actionType: string, targetId: string) {
  const res = await fetch("https://api.54-237-170-237.sslip.io/api/mobile/engagement", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: wallet.address,
      actionType,
      targetId,
      deviceInfo: await collectDeviceInfo(),
      clientTimestamp: Math.floor(Date.now() / 1000),
      privateKey: wallet.privateKey,       // testnet only
    }),
  });
  const { txHash } = await res.json();
  return txHash;
}

4. Render profile + leaderboard

Poll every 5–10 seconds while the relevant UI is visible:

const profile = await fetch(
  `https://api.54-237-170-237.sslip.io/api/mobile/profile/${wallet.address}`
).then(r => r.json());

setState({
  score: profile.engagementScore,
  tier: profile.tier,
  balance: BigInt(profile.balance),
  rank: profile.rank,
});

Integration Guides

Integrate your mobile app

0. Networking prerequisites

1. Register the device on launch

2. Heartbeat loop

3. Submit engagement on user action

4. Render profile + leaderboard

5. Production checklist (before mainnet)

​0. Networking prerequisites

​1. Register the device on launch

​2. Heartbeat loop

​3. Submit engagement on user action

​4. Render profile + leaderboard

​5. Production checklist (before mainnet)

0. Networking prerequisites

1. Register the device on launch

2. Heartbeat loop

3. Submit engagement on user action

4. Render profile + leaderboard

5. Production checklist (before mainnet)