Troubleshooting
symptom, cause, fix.

01The app does not start properly

02Ads and points

03Ad callbacks: points not credited after a video

Work backwards from the user. You need the user's uid (console → Users) and Firebase console → Firestore Database. These collections are server-only; the app cannot read or change them.

1. Find the sessionOpen the collection adSessions and filter on uid = the user's uid. Take the newest createdAt. Read status, placement, verifiedBy and txId. No session at that time means requestAdSession refused (the app showed the limit, cooldown or emulator message) or the app could not reach Functions (The app does not start properly).
2. Status verifiedThe callback was applied. Open ssvEvents/<verifiedBy>_<txId> and read outcome: credited (with points and placement), ignored:daily_cap or ignored:no_user_or_banned. A credited points video also has a row in users/{uid}/ledger whose ref is the session id (the nonce). Placement spin or scratch grants a spin or a card, not points.
3. Status pending or expiredNo valid callback matched this session. Read the callback logs, from the firebase/ folder (or add --project YOUR_PROJECT_ID):

   firebase functions:log --only ssvAdmob,ssvUnity,ssvIronsource -n 200

   The same logs are in Firebase console → Functions → the function → Logs.
4. Match what you see to the tableThen fix the cause and watch one more video.

The session's network field is the network chosen in the console when the session opened. In waterfall mode the network that really served and called back is in verifiedBy and in ssvEvents.network.

04Ad callbacks: fraud flags on your own test views

A callback with a valid signature that does not fit its session credits nothing, answers 200 (so the network stops retrying), writes a fraudFlags row and marks the user flagged. Console → Fraud flags shows When, uid, Reason and Detail. Detail holds the network, transaction id and nonce, plus sessionUid or sessionStatus where they apply.

1. Clear the test flagsConsole → Fraud flags: type why it is fine and clear it. The user's flagged mark goes away when no other open flag remains. Clear them: a flagged user's offerwall conversions are held for review.
2. Give the points back if neededConsole → Users → the user → Adjust points with a reason (ledger type admin).

A callback without a nonce is not a fraud flag: it is recorded as ignored:no_nonce (above).

05Ad callbacks: signature verification fails (403)

Start with the self-test in Test the callbacks. It signs a callback with the secret you hold: if the self-test passes but real callbacks fail, the network signs with another secret or the request is changed on the way; if the self-test fails, the console holds another secret than you think.

After you change a secret, wait about 30 seconds before testing again (the Functions config cache).

06Offerwalls, surveys and revenue

07Cash wallet

08Payout requests

The app shows a translated message for each refusal reason (app/lib/ui/widgets/common.dart); the reason itself is in the Functions log of requestPayout.

09PayPal Payouts

10Gift cards

11Operator console

12Operator console: Firebase credentials

The console reaches Firebase with the Admin SDK and reads only these variables for it (admin/src/firebase.ts, admin/src/kit.ts): GOOGLE_APPLICATION_CREDENTIALS, FIREBASE_PROJECT_ID (or GCLOUD_PROJECT / GOOGLE_CLOUD_PROJECT), FIRESTORE_EMULATOR_HOST and ADMIN_DATA. npm start and npm run start:dist load admin/.env; starting node or tsx yourself, or the Docker image, does not, so pass the variables from the host (docker run --env-file .env …).

1. Read the start-up lineThe log says where the data comes from: [admin] data: Firestore (service account), [admin] data: Firestore emulator … or [admin] data: built-in SAMPLE data (no Firebase).
2. Open console → Status"Firestore is reachable" and "App config written to Firestore" show the error text when they fail.

13Operator console: database (SQLite or Postgres)

The console keeps its own data (team, sessions, settings, encrypted secrets, audit log) in one place: the SQLite file admin/data/admin.sqlite (in Docker /app/data), or Postgres when DATABASE_URL is set. On Postgres the tables are named mk_watchandearn_* and are created at the first start; Postgres 14 or newer is needed (the schema uses CREATE OR REPLACE TRIGGER). App users and points are never in this database: they are in Firestore.

Move from SQLite to Postgres

Nothing copies the data for you. Do it at a quiet time.

1. Export the settingsIn the old console, as the owner, open Export and download the export. It holds the settings, not the secrets, and wallet addresses in clear: keep it safe. Note your team members, and collect every secret from its source (list).
2. Start on PostgresStop the old console, set DATABASE_URL, keep the same ADMIN_SECRET_KEY and start. The tables are created and a setup code is printed. This first start writes default settings to Firestore until you import.
3. RestoreCreate the owner with the setup code, import the export, enter every secret again and add the team.
4. CheckConsole → Status shows no blocker; run the callback self-tests (Test the callbacks).

14Operator console: sign-in and cookies behind a reverse proxy

What the console does (admin/packages/admin-kit/server/kit.ts):

• The session cookie mk_admin is HttpOnly, SameSite=Strict, Path=/, has no Domain (this host name only) and lasts 12 hours.
• It is marked Secure only when the request reached the console over https, or when the first value of the X-Forwarded-Proto header is https. There is no "trust proxy" setting: the header is always honoured, so let only your proxy reach port 8790.
• The paths are fixed: /admin (console), /admin/api (its API), /wae-admin/ (product pages and their API); / redirects to /admin. Serve the console at the root of its own host name, for example admin.example.com; a path prefix such as example.com/tools/ is not supported.
• Every API request that changes something must carry the header x-mikodes-admin: 1 (protection against cross-site requests). The console's own pages send it.

An nginx example (adjust the host name and certificate lines to your server):

server {
  listen 443 ssl;
  server_name admin.example.com;
  # ssl_certificate and ssl_certificate_key lines here
  location / {
    proxy_pass http://127.0.0.1:8790;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

15Development