Documentation

Introduction

CashLoop | Native Android (Kotlin/Compose) with Laravel Admin Panel

Thank you for purchasing CashLoop Android.

CashLoop is a ready-to-launch native GPT ("get-paid-to") rewards app for Google Play, powered by a complete Laravel 13 admin panel and a frozen mobile API. Users earn real money by installing and playing apps and games, completing surveys, finishing offerwall tasks and watching rewarded video — then withdraw it as gift cards, prepaid cards, e-wallet payouts or crypto. It is designed for publishers who want a real reward economy with an auditable money trail, not a coin counter in local storage.

Every balance change in CashLoop is a ledger row. Nothing writes a wallet balance directly; a conversion, a quest claim, a referral payout and a withdrawal all append to wallet_transactions, and an hourly wallet:verify job re-sums the ledger and exits non-zero if any balance has drifted. This is the difference between a demo and something you can put real payouts through.

Earning is attributed by click id. When a user opens an offer, the server mints a uuid, hands the app a tracked URL containing it, and the partner returns that same id on their server-to-server postback. That is how a conversion finds its user — a raw user id is never sent to a third party, and the SDKs never touch a wallet.

Key Value Propositions:

• For Users: Five clean tabs — Apps, Games, Surveys, Cashout, Profile — with a live balance in the header, boosted payouts shown with the original price struck through, daily streaks, claimable quests, levels, promo codes, referral earnings, and withdrawals that show every unmet rule at once instead of one at a time.
• For Publishers: Run the whole platform from one Laravel dashboard — partners and their credentials, offers and categories, boosts, quests, levels, streak rewards, promo codes, cashout catalogue and withdrawal queue, fraud rules, postback logs and an immutable audit trail. The home screen itself is admin-built: reorder or switch off a whole section without an app release.
• For Buyers / Developers: Full Kotlin source (Compose, Hilt, Retrofit, kotlinx.serialization, DataStore Proto), full Laravel source, migrations and seeders — no SQL dump anywhere — a frozen and documented API v1 contract, six languages, nine colour presets, and eight offerwall partners already wired with a fail-closed postback layer.

What's Included:

• Full native Android source code (Kotlin + Jetpack Compose, 200+ source files)
• Laravel 13 admin panel with the frozen mobile API v1
• 17 migrations and 22 seeders — the schema is the migrations, there is no SQL dump
• 9 colour presets and an onboarding variant switch
• 8 offerwall / survey partners: 4 native SDKs + 4 hosted walls, plus a generic adapter
• Usage-verified offers (on-device play-time verification via UsageStatsManager)
• Multi-language support (en, tr, de, es, it, ar)
• Setup and deployment documentation (this guide)
• Android release checklist

Key Features:

• Real Money Wallet: decimal(14,6) balances handled with bcmath, never floats. Cash and coins, pending vs available, and a full transaction history the user can scroll.
• Offers, Games and Surveys: One paginated feed implementation with three configurations, sort chips (payout, new, popular, quick, rating), category and provider filters, search, and admin-built sections above the list.
• Reward Ladders: An offer can pay in steps ("reach level 5", "spend 7 days in app") with requirements and per-step payouts shown on the detail screen.
• Boosted Payouts: When a boost is running the API sends original_payout and boost_percent, so the app renders the struck-through price without deciding anything itself.
• Usage-Verified Offers: For offers you run yourself, the app measures real on-device play time and posts it; the server decides whether it qualifies.
• Offerwall Partners: Native SDKs for BitLabs, ayeT-Studios, MyChips and Digital Turbine, hosted walls for CPAlead, Torox, Revenue Universe and MM Wall — with a registry that always falls back to the tracked URL rather than opening nothing.
• Cashout Catalogue: Gift cards, prepaid cards, e-wallets and crypto grouped by brand, already filtered server-side to what this user can actually use.
• Quests, Streaks and Levels: Claimable — never auto-credited — with a badge on the Profile tab the moment something becomes claimable.
• Referrals: Signup bonus for both sides, a percentage of the friend's lifetime earnings, and an optional bonus on their first withdrawal.
• Promo Codes: Redeemable in-app, rate-limited separately because codes are guessable by design.
• Server-Side Kill Switches: A feature switched off in the panel has its tab removed, not greyed out.
• Maintenance & Force Update Gates: Computed server-side from X-Platform and X-App-Version, and deliberately terminal — no back gesture, no "continue anyway".
• Guest-to-Account Flow: Anonymous Firebase session on first launch; signing in with Google, Facebook or email upgrades it in place, so the balance and streak carry over with no merge step.
• Fraud & Integrity Tooling: Configurable fraud rules, user flags, postback logs with redacted payloads, and immutable audit rows.
• White-Label Ready: Colour presets, app icon, name, locales, ad units, push, legal pages and home-screen layout — all changeable without touching gameplay code.

App identifiers (current project):

• Android applicationId / namespace: com.cashparty.rewards.app
• versionCode 10 · versionName 2.0
• Min SDK 26 · Target / Compile SDK 36 · JDK 17+ · AGP 9 (Kotlin built in)
• Release API origin baked in as https://panel.cashloop.app/, overridable at runtime

Support: For questions or issues, contact us via the CodeCanyon messaging system.

📦 What's Included in the Package

After purchasing and downloading CashLoop Android, your package contains everything you need to build, rebrand and publish the native Android app to Google Play, plus the backend it runs against:

🤖 Native Android App Overview

CashLoop Android is a single-module Compose app plus one small library module. There is no Flutter, no WebView shell and no second UI framework — every screen you see is Compose.

Where each setting lives

Configuration is split deliberately, so public and secret values never share a home and so the things that must change without a release actually can:

⚡ Android Quick Start

Four things must be in place before the app can do anything useful:

# Emulator, against a local panel on the host machine (default)
./gradlew :app:installDebug

# Physical device, against your LAN IP or a tunnel
./gradlew :app:installDebug -Pcashloop.apiBaseUrl=https://abc123.ngrok.io/

# Unit tests
./gradlew :app:testDebugUnitTest

⚙️ Android Configuration

1. API Base URL

The origin is resolved from three places, in this order — later wins:

// app/build.gradle.kts
val debugApiBaseUrl: String =
    (findProperty("cashloop.apiBaseUrl") as String?) ?: "http://10.0.2.2:8000/"
val releaseApiBaseUrl: String =
    (findProperty("cashloop.apiBaseUrl") as String?) ?: "https://panel.cashloop.app/"

10.0.2.2 is the Android emulator's route to the host machine — localhost inside the emulator is the emulator. On a physical device you must use a LAN IP or a tunnel.

unzip -p app-release.apk classes.dex | strings | grep -i "https://"

2. Package ID & version

android {
    namespace = "com.cashparty.rewards.app"
    compileSdk = 36

    defaultConfig {
        applicationId = "com.cashparty.rewards.app"
        minSdk = 26
        targetSdk = 36
        versionCode = 10
        versionName = "2.0"
    }
}

minSdk is 26 rather than 24 on purpose: the Arcade type scale drives the variable font weight axis through FontVariation, which the platform ignores below API 26 — every weight would silently render at the axis default.

3. Firebase & google-services.json

1. Firebase Console → Add app → Android.
2. Package name: exactly your applicationId.
3. Add your debug and release SHA-1 and SHA-256 fingerprints (required for Google Sign-In).
4. Download google-services.json and place it at app/google-services.json, replacing the bundled one.
5. Enable Authentication (Anonymous, Email/Password, Google, Facebook), Cloud Messaging and Remote Config.

4. Strings & SDK keys

Everything compiled into the binary lives in app/src/main/res/values/strings.xml.

🎨 Reskin & Layout Variants

Two presentation axes are switched by a single Kotlin constant plus a rebuild. Everything else that changes the look of the app — which sections appear on a feed, in what order, with what titles — is admin-driven and needs no rebuild at all.

Colour presets (1–9)

File: app/src/main/java/com/cashparty/rewards/app/ui/theme/arcade/ArcadePresets.kt

object ArcadePresets {
    /**
     * CHANGE THIS (1..9) TO SWITCH COLOR PRESET.
     * 1 Ember Aurora  2 Emerald Pulse  3 Sunset Vinyl  4 Midnight Gold
     * 5 Neon Coral    6 Ink & Parchment  7 Bronze Luxury  8 Arcade
     * 9 CashLoop  <- active
     */
    const val SELECTED = 9
}

Each preset carries both the light and the dark role set, so switching one constant restyles the entire app in both modes — accents, canvas, surfaces, cards, dividers, text, and the CTA/social-proof gradients.

To add a tenth preset: copy an existing ArcadePreset(...) block, give it a name, add a branch to the when in active, and set SELECTED. The data class lists every role the theme needs, so the compiler tells you if you missed one.

Onboarding variant

File: .../ui/onboarding/OnboardingRoute.kt → OnboardingConfig.SELECTED

All variants share one completion pipeline — they differ in how they pitch the product, not in plumbing. Variant 1 (Deck) is the one implemented on Android; the remaining slots fall back to Deck until their scaffolds are ported, so changing the constant is safe but currently a no-op for 2–5.

🛠 Admin Panel → App Config

Most of what used to be an app constant is served by GET /api/v1/config and applied on the next launch. The app fetches it before sign-in so a broken auth flow cannot hide a "we are down" message.

Where to edit these in the panel:

🏷 Branding — Name, Icon, Theme

🌐 Android Locales

Six languages ship: en, tr, de, es, it, ar. The default (untagged) res/values/strings.xml is English and is the fallback for any key a translation is missing.

Per-app language selection uses AppCompatDelegate locale storage — the manifest declares AppLocalesMetadataHolderService with autoStoreLocales=true, so the choice survives reinstall-free upgrades and appears in Android 13+ system settings. The in-app picker is ui/settings/LanguageScreen.kt, which lists what GET /api/v1/locales returns.

Arabic ships with android:supportsRtl="true"; the Compose layouts use start/end padding rather than left/right throughout, so RTL mirrors correctly.

💳 Ads, Push & Offerwall SDKs

Ads

Two networks, both optional, both configured server-side:

• Google AdMob — banner, interstitial, rewarded and native unit ids from config.ads.admob. The application id is the one exception and lives in the manifest via @string/admob_app_id.
• Unity Ads — banner, interstitial and rewarded placements from config.ads.unity, managed by ads/UnityBannerAdManager.kt and ads/UnityRewardedAdManager.kt.

A rewarded view pays rewarded_ad_reward_coins, capped at daily_rewarded_ad_limit per day. Setting either network's enabled to false, or leaving its unit ids blank, removes the surface entirely — the app does not render an empty ad slot.

Push

Both channels are wired:

• FCM — service/CashLoopMessagingService.kt, registered in the manifest for com.google.firebase.MESSAGING_EVENT. Tokens are posted to POST /auth/device.
• OneSignal — initialised with config.push.onesignal_app_id; broadcast sends come from the panel at /admin/notifications. The REST key stays in the Laravel .env.

OneSignal is initialised in MainActivity only when config.push.onesignal_app_id is non-empty, and the user is identified with OneSignal.login(userId) so the panel can target an individual account.

Offerwall SDKs

Four native SDKs are compiled in. None of them credits anything — they open a wall, and rewards arrive later by server-to-server postback:

📁 Android Project Structure

cashloop-android/
├── app/
│   ├── google-services.json          # Firebase identity — replace with yours
│   ├── build.gradle.kts              # applicationId, versions, API origins, dependencies
│   ├── proguard-rules.pro
│   └── src/
│       ├── main/
│       │   ├── AndroidManifest.xml
│       │   ├── res/                  # values(+ -en -tr -de -es -it -ar), drawable, font, mipmap, raw
│       │   └── java/com/cashparty/rewards/app/
│       │       ├── CashLoopApplication.kt
│       │       ├── api/              # Retrofit service, envelope, error codes, paging, interceptors
│       │       ├── ads/              # AdMob + Unity rewarded/banner managers
│       │       ├── contracts/        # Google Sign-In activity contract
│       │       ├── data/
│       │       │   ├── auth/         # AuthManager, TokenStore, DeviceIdProvider
│       │       │   ├── config/       # RemoteConfigService
│       │       │   ├── models/       # Wire models — one file per API area
│       │       │   └── repositories/ # 14 repositories, one per API area
│       │       ├── datastore/        # Proto + preferences persistence
│       │       ├── di/               # Hilt modules (App, Network, Firebase, Offerwall, Activity)
│       │       ├── offerwall/        # Launchers, registry, SDK config store, usage tracker
│       │       ├── service/          # FCM messaging service
│       │       ├── usage/            # UsageStatsManager observer, reporter, diagnostics
│       │       ├── ui/
│       │       │   ├── MainActivity.kt, CashLoopApp.kt, CashLoopAppState.kt
│       │       │   ├── shell/        # AppHeader, MainTabBar, MainTabs
│       │       │   ├── tabs/feed/    # Apps · Games · Surveys (one screen, three configs)
│       │       │   ├── tabs/profile/
│       │       │   ├── offers/       # List, detail, my offers, partners
│       │       │   ├── cashout/      # Catalogue, request sheet, validation
│       │       │   ├── wallet/       # Transactions
│       │       │   ├── engagement/   # Quests, streak, promo codes
│       │       │   ├── referral/ notifications/ settings/ auth/ onboarding/
│       │       │   ├── gate/         # Maintenance + force update
│       │       │   ├── splash/ welcome/ home/account/
│       │       │   ├── common/       # Shared composables, ads, arcade widgets
│       │       │   └── theme/arcade/ # Presets, tokens, type scale, motion
│       │       └── util/             # Money, colours, modifiers, tracked links, text field state
│       └── test/                     # 7 JVM test classes
├── core/datastore-proto/             # Protobuf schema for persisted settings
├── dummylib/ToroxSDK-v6.4.aar        # Torox SDK, not published to a public repo
├── gradle/libs.versions.toml         # Single source of truth for every dependency version
├── settings.gradle.kts               # Repositories, module list, JDK 17 check
├── debug.keystore                    # Bundled so debug builds from CI stay upgradable
└── build.gradle.kts

🏗 Build & Run (Gradle)

# Debug build + install
./gradlew :app:assembleDebug
./gradlew :app:installDebug

# Point a build at a different backend
./gradlew :app:installDebug -Pcashloop.apiBaseUrl=https://panel.example.com/

# Unit tests (JVM, no device needed)
./gradlew :app:testDebugUnitTest

# Instrumented tests (device/emulator required)
./gradlew :app:connectedDebugAndroidTest

# Release artefacts
./gradlew :app:assembleRelease      # APK
./gradlew :app:bundleRelease        # AAB for Play

# When Gradle misbehaves
./gradlew clean && ./gradlew --stop

Signing notes

The project ships a bundled debug keystore (debug.keystore) so debug builds from any machine or CI runner stay mutually upgradable. The release build type never falls back to it: with no release key configured, assembleRelease succeeds and produces app-release-unsigned.apk, which you cannot upload until you supply your own key.

That is deliberate. debug.keystore is inside this package, so everyone who has the source has the key — a release signed with it could be re-signed by anyone into an update your users' devices would accept.

Supply your key through Gradle properties or environment variables, never in the repository:

# ~/.gradle/gradle.properties — outside the project, so it is never committed
cashloop.releaseStoreFile=/absolute/path/to/release.jks
cashloop.releaseStorePassword=...
cashloop.releaseKeyAlias=cashloop
cashloop.releaseKeyPassword=...

# or as environment variables in CI
CASHLOOP_RELEASE_STORE_FILE      CASHLOOP_RELEASE_STORE_PASSWORD
CASHLOOP_RELEASE_KEY_ALIAS       CASHLOOP_RELEASE_KEY_PASSWORD

Other build facts worth knowing

• AGP 9 has Kotlin built in. The org.jetbrains.kotlin.android plugin must not be applied — doing so breaks the build.
• Core library desugaring is on, so java.time works down to API 26.
• MultiDex is enabled — with five ad/offerwall SDKs the method count is well past 64k.
• R8 is on for release — isMinifyEnabled and isShrinkResources are both true. That is what makes proguard-rules.pro do anything: it carries the keep rules for Retrofit, kotlinx.serialization and the offerwall SDKs, plus an -assumenosideeffects rule that strips android.util.Log from the shipped build. With minification off, none of that ran and the published APK carried readable class names and every debug log.
  The release build is verified to complete with R8 enabled. If you add an SDK that uses reflection, add its keep rules and re-run ./gradlew :app:assembleRelease before shipping.
• Repositories are deliberately unfiltered in settings.gradle.kts. The ad SDKs pull transitive artifacts from unrelated group ids (Unity Ads → play-services-cronet → org.chromium.net:cronet-api), and a group regex filter turns each of those into an unresolved dependency.

Sanity checklist before the first Play upload

1. applicationId is yours, not com.cashparty.rewards.app.
2. releaseApiBaseUrl points at your panel and ends in a slash.
3. google-services.json is your Firebase project.
4. Release SHA-1 / SHA-256 are registered in Firebase (and in Play App Signing).
5. admob_app_id and the Facebook ids are yours — the package ships placeholders, not working credentials (see Strings & SDK keys). The Google web client id is not in strings.xml at all; it is generated from your google-services.json.
6. A real release keystore is configured — otherwise the build output is app-release-unsigned.apk and Play will reject it.
7. versionCode is higher than anything you have uploaded before.
8. Legal pages exist in the panel — Play requires a reachable privacy policy URL.
9. The Play Data safety form matches what the app actually collects (advertising id, usage stats if you enable usage-verified offers).

🧭 Feature Walkthrough — the Five Tabs

The shell is five equal tabs with no centre action: Apps · Games · Surveys · Cashout · Profile. Tabs stay composed rather than being swapped, so scroll position and in-flight loads survive a tab switch.

App screenshots

Click any screenshot to enlarge it.

onboarding.png
Onboarding deck, first card

apps.png
Apps tab — sections, offers, balance

games.png
Games tab, sort chips visible

offer-detail.png
Multi-step reward ladder

partners.png
Partners / offerwall grid

cashout.png
Cashout catalogue, boosted card

profile.png
Profile, level progress

settings.png
Settings

Above them sits the persistent header, fed by one call to GET /home:

• Balance chip — the withdrawable available figure, formatted in the currency from config.economy.currency_code. Tapping it selects the Cashout tab rather than pushing a route, so there is no back stack to unwind.
• Streak chip — day count, and a claim indicator when today's streak reward is available. Tapping selects Profile.
• Notifications — unread count.
• Settings.

The header refetches every time the shell resumes, not once per process: a balance moves on screens the header cannot see — an offer that converted, a withdrawal that was requested, a quest that was claimed.

Tab badges are derived from the same payload: a count badge on Profile when quests are claimable, and a plain dot on Apps when offers are in progress (what matters is that something is unfinished, not how many).

Back behaviour: on any secondary tab, back returns to Apps. On Apps, back asks for a second press within two seconds before leaving the app.

1. Apps Tab

The default tab. An admin-built section stack sits above an infinite, filterable offer list.

• Sections come from GET /home?screen=earn — carousels, grids, lists, banners, partner rows and hero blocks, in whatever order the panel says. A section with no items is omitted server-side, never rendered empty.
• The list is GET /offers?type=app, paginated, with sort chips for payout, new, popular, quick and rating, plus category and provider filters and search.
• Payout display: when original_payout and boost_percent are present, the original is struck through and the boost badge renders. The app never computes a boost itself.

2. Games Tab

The same screen with type=game and screen=games. Apps, Games and Surveys are one implementation with three configurations — building them as three screens would have meant maintaining the same paging, sorting and section rendering three times over.

3. Surveys Tab

Backed by the dedicated GET /surveys endpoint rather than a type filter, with its own narrower set of sort chips — a chip the server would reject is never rendered. Survey partners are typically opened through their SDK or hosted wall rather than as individual offers.

4. Cashout Tab

Two panes: Cashout (the catalogue) and My Withdrawals.

• Options arrive from GET /cashout/options grouped by brand, already filtered server-side to what this user can use — geo-blocked and out-of-stock rows are dropped, and a group that empties is dropped with them. The app should never show a card that errors on tap.
• A card is either a fixed denomination or a range with a minimum. Bonus and fee percentages are null rather than zero when absent, so the +30% BONUS pill renders on presence, not on a magic value.
• The payout field is labelled by the server (target_label: "Email address", "Wallet address", "Phone number"), so a new payout rail does not need an app release to be labelled correctly.
• Requesting a withdrawal holds the money immediately — available drops at once, cash_balance only when it is paid.
• A rejected request returns every unmet rule at once in error.fields.reasons, so the user is not told about one blocker at a time.
• Pending requests can be cancelled, which releases the hold.

5. Profile Tab

Identity, level progress and everything that is not an offer:

• Balance summary and a link into the full transaction ledger (GET /wallet/transactions, filterable by type)
• Quests and streak — both claimed, never auto-credited
• Levels — progress and what the next level unlocks
• Promo codes — redeemed in a sheet, rate-limited separately
• Refer a friend — code, share sheet, friend list and referral earnings
• My account, Language, Settings, Sign out

Settings itself carries dark mode, sound effects, push toggle, language, the legal/help links from config.links (a row is hidden when its URL is null), rate-this-app, sign-in for guests, and account deletion. Deleting an account soft-deletes it server-side — financial history is retained — and drops the user back to a fresh anonymous session rather than a sign-in wall.

Offer Detail & My Offers

Offer detail (GET /offers/{id}) adds two things the list does not carry: the reward ladder (steps — each with its own payout and completion criteria) and requirements (device, OS version, country, "new users only"). A troubleshooting endpoint (GET /offers/{id}/troubleshoot) backs the "I did this and wasn't paid" screen with self-help steps and the offer's current status.

My Offers (GET /me/offers) splits into in progress and completed, and is what the dot on the Apps tab refers to.

Partners lists every enabled offerwall (GET /providers); opening one calls POST /providers/{slug}/open and hands the result to the launcher registry.

💰 How Earning Works

Four ways money enters a wallet, and all four end in the same place — a ledger row.

Money rules that matter

• Spend against available, not cash_balance. pending is money that has arrived but is not yet withdrawable; a requested withdrawal is already held out of available.
• Balances are decimal(14,6) handled by bcmath. Never floats — 0.1 + 0.2 !== 0.3, and a cent lost per conversion is real money.
• Nothing writes a balance except WalletService. It locks the wallet row and writes the matching wallet_transactions entry in the same database transaction.
• Ledger and audit rows are immutable. A mistake is corrected with a compensating entry; the models throw on update and delete.
• wallet:verify runs hourly and exits non-zero if any balance disagrees with its ledger. Wire it to alerting — it is the canary for a balance written outside WalletService.

Usage-Verified Offers

For offers you run yourself (no partner postback to rely on), CashLoop can verify that the user actually used the installed app. This is the only feature that needs a sensitive permission.

1. An offer is marked verification_mode = usage in the panel with a target package name and a play-time threshold.
2. When the user opens it, the launcher registry starts watching before anything opens — the click time is the lower bound of the usage query, and a bound set afterwards would miss the session the user just played.
3. The app asks for Usage access (PACKAGE_USAGE_STATS), which is a Settings screen the user must visit; it is requested in context, when the first such offer is opened, not at launch.
4. On the next app resume, UsageReporter queries UsageStatsManager for every watched package and posts the result to POST /me/offers/{id}/usage.
5. The server decides whether it qualifies and credits accordingly. The app measures, posts and acts only on the verdict — it never decides that something was earned.
6. Anything credited that the user has not seen yet is shown as a celebration on the next resume; multiple offers are summed into one dialog rather than stacking.

🗺️ System Flowcharts

1. Master system architecture

┌──────────────────────────────────────────────────────────────┐
│                    CashLoop Android (Compose)                │
│   Hilt · Retrofit · kotlinx.serialization · DataStore Proto  │
└───────┬───────────────┬────────────────────┬─────────────────┘
        │ REST          │ SDKs               │ Firebase
        ▼               ▼                    ▼
┌────────────────┐ ┌──────────────────┐ ┌──────────────────────┐
│  Laravel 13    │ │ Offerwall SDKs   │ │ Auth (identity)      │
│  /api/v1       │ │ BitLabs · ayeT   │ │ Cloud Messaging      │
│                │ │ MyChips · DT     │ │ Remote Config        │
│  MySQL 8 —     │ └────────┬─────────┘ └──────────────────────┘
│  source of     │          │ user completes an offer
│  truth for     │          ▼
│  EVERYTHING    │ ┌──────────────────┐
│  financial     │◀│ Partner postback │  server-to-server only
└───────┬────────┘ └──────────────────┘
        │
        ▼
  wallet_transactions  →  quests · levels · referrals  →  cashout

There is no second datastore and no realtime database. MySQL is the source of truth for every balance, conversion and withdrawal; Firebase supplies identity, push and one config key.

2. Boot & authentication

3. Click → postback → wallet

4. Cashout flow

5. Data ownership (what lives where)

🎨 Branding and Customization

Rebranding the app from scratch

Home sections (admin-driven)

Every feed screen is a stack of sections defined at /admin/app-sections. A section is a row in app_sections and looks like this on the wire:

{
  "key": "best_for_you",
  "title": "Best for You",
  "subtitle": null,
  "icon": null,
  "layout": "carousel",
  "data_source": "featured_offers",
  "show_view_all": true,
  "view_all_filters": {"sort": "payout"},
  "items": [ /* offers, providers, quests or banners */ ]
}

Android customization cheat sheet

🟢 Getting Started

What you are setting up, and why

CashLoop is two deployables plus a Firebase project. The app cannot do anything on its own: it holds no content, no economy and no balances. Getting it running means standing up the backend first, giving the app a way to reach it, and giving both sides the same Firebase identity.

The 6 stages at a glance

🚀 Run the App From Scratch — Complete Setup Guide

📋 Prerequisites

php -v            # 8.3+
php -m | grep -E 'bcmath|pdo_mysql|gd|mbstring'
composer -V
node -v           # 20+
mysql --version   # 8+
java -version     # 17+

🔧 Step 1 — Android Project Setup

🔥 Step 2 — Firebase Project Setup

# Debug (bundled keystore)
keytool -list -v -keystore debug.keystore -alias androiddebugkey \
        -storepass android -keypass android

# Your release keystore
keytool -list -v -keystore /path/to/release.jks -alias <your-alias>

⚙️ Step 3 — Firebase Remote Config

CashLoop uses exactly one Remote Config parameter. Everything else that used to live in a console is served by GET /api/v1/config, so there is only one place a value can be wrong.

1. Firebase Console → Remote Config → Create configuration.
2. Parameter key api_base_url, value = your origin with the trailing slash.
3. Publish changes. An unpublished parameter does not exist as far as the app is concerned.

🗄️ Step 4 — Laravel Admin Panel Setup (Local)

cd cashloop-admin-panel
composer install
npm install

mysql -u root -p -e "CREATE DATABASE cashloopdb CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

cp .env.example .env
php artisan key:generate
php artisan jwt:secret

APP_NAME="CashLoop"
APP_URL=http://127.0.0.1:8000

DB_DATABASE=cashloopdb
DB_USERNAME=root
DB_PASSWORD=root

# Seeded admin — set a real password BEFORE seeding.
ADMIN_EMAIL=you@your-domain
ADMIN_PASSWORD=<a real password>
ADMIN_NAME="CashLoop Admin"

# Firebase service account JSON, relative to the project root
FIREBASE_CREDENTIALS=storage/app/firebase/service-account.json
FIREBASE_PROJECT=app

SESSION_DRIVER=database
QUEUE_CONNECTION=sync         # database or redis under load

php artisan migrate:fresh --seed   # schema + core data
php artisan storage:link           # offer icons, logos, banners

# Optional: demo users, offers, conversions, promo codes
php artisan db:seed --class=DemoSeeder

npm run dev          # Vite, in one terminal
php artisan serve    # http://127.0.0.1:8000, in another

curl -s http://127.0.0.1:8000/api/v1/config | head -c 400

📊 Step 5 — Database (Migrations & Seeders)

What the migrations create

Seeders

# Fresh local rebuild
composer refresh          # migrate:fresh --seed
composer refresh-demo     # …plus demo fixtures

# Production
php artisan migrate --force
php artisan db:seed --class=CoreSeeder --force

Verify

php artisan tinker --execute="echo App\Models\Provider::count().' providers, '
  .App\Models\Offer::count().' offers, '
  .App\Models\User::count().' users';"

php artisan wallet:verify     # must exit 0

🔐 Step 6 — Firebase Auth Bridge

Firebase owns identity; the API owns everything else. The bridge is one endpoint.

curl -X POST http://127.0.0.1:8000/api/v1/auth/firebase \
  -H "Content-Type: application/json" \
  -H "X-Platform: android" -H "X-App-Version: 2.0" \
  -d '{"id_token":"<a real Firebase ID token>"}'

🚀 Step 7 — Deploy Laravel to Production

git clone <repo-url> /var/www/cashloop && cd /var/www/cashloop

composer install --no-dev --optimize-autoloader
npm ci && npm run build

cp .env.example .env
php artisan key:generate
php artisan jwt:secret

php artisan migrate --force
php artisan db:seed --class=CoreSeeder --force
php artisan storage:link

php artisan config:cache && php artisan route:cache \
  && php artisan view:cache && php artisan event:cache

Production .env checklist

APP_ENV=production
APP_DEBUG=false                 # non-negotiable
APP_URL=https://your-domain

ADMIN_EMAIL=you@your-domain
ADMIN_PASSWORD=<12+ chars, not a common default>   # see the note below

FIREBASE_CREDENTIALS=storage/app/firebase/service-account.json
QUEUE_CONNECTION=database
SESSION_DRIVER=database
ONESIGNAL_APP_ID=…
ONESIGNAL_REST_API_KEY=…

npm install
npm run build

Permissions

chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

Queues

Conversion crediting, referral payouts and push notifications run through event listeners. With QUEUE_CONNECTION=sync they run inline — fine at low volume and simplest to debug — but move to database or redis under load.

[program:cashloop-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/cashloop/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/cashloop/storage/logs/worker.log
stopwaitsecs=3600

Scheduler — one cron entry, and it is not optional

* * * * * cd /var/www/cashloop && php artisan schedule:run >> /dev/null 2>&1

Shared hosting (cPanel / Hostinger / Namecheap)

1. Upload the project outside public_html; point the domain's document root at the project's public/ directory.
2. Set the PHP version to 8.3 and enable bcmath, pdo_mysql, gd, zip, fileinfo.
3. Create the database and user in cPanel, then run the artisan commands over SSH (or the host's terminal). Hosts with no SSH are a poor fit — you cannot run migrations or a queue worker.
4. Add the scheduler cron entry through the cPanel Cron Jobs UI.
5. Use QUEUE_CONNECTION=sync if you have no way to keep a worker alive.

Cloud / VPS

A Linux host with PHP 8.3, nginx, MySQL 8 and Supervisor is the intended target: nginx serving public/, PHP-FPM, Supervisor running the queue worker, and system cron running the scheduler. Managed platforms (Forge, Ploi, Vapor) work with no changes.

Routine deploys

php artisan down --render="maintenance"
git pull
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan config:cache && php artisan route:cache && php artisan view:cache && php artisan event:cache
php artisan queue:restart
php artisan up

Backups, in order of "cannot be reconstructed"

1. wallet_transactions — the ledger. Balances are derived from it; lose it and you cannot prove what anyone is owed.
2. conversions, cashout_requests — what was earned and what was paid.
3. audit_logs, user_flags — who decided what.
4. storage/app/public — uploaded icons, logos, banners.
5. Everything else is recoverable from migrations, seeders and partner feeds.

🔁 Step 8 — Partner Postbacks

Each partner gets one URL:

https://your-domain/api/postback/{slug}

Copy it from the partner's edit screen in the panel, which also shows the query template to paste into the partner's dashboard. The slug selects the adapter, and the adapter owns the IP allowlist and signature check. There is no session or token auth on this route — partners cannot carry one — so rate limits are keyed per provider, and one misconfigured partner cannot exhaust everyone else's budget.

Before switching a partner to active

Seeding credentials from .env (optional)

The panel is the authority for provider settings, but ProviderSeeder will write an initial value on first run from these, so a fresh deploy can come up already configured. Once a setting exists, re-seeding leaves it alone — changing it here later does nothing.

# CPAlead — its postback carries a `password` parameter rather than a signature.
# Set this OR CPALEAD_POSTBACK_IPS, or CPAlead postbacks are rejected.
CPALEAD_WALL_SLUG=
CPALEAD_PUBLISHER_ID=
CPALEAD_POSTBACK_PASSWORD=
CPALEAD_POSTBACK_IPS=
CPALEAD_COUNTRIES=TR,US,DE,GB

# BitLabs — every callback is HMAC-signed, so the secret is mandatory.
BITLABS_APP_TOKEN=
BITLABS_APP_SECRET=

# Torox — every postback is signed; the placement key is mandatory.
TOROX_APP_ID=
TOROX_PUB_ID=
TOROX_TOKEN=
TOROX_POSTBACK_IPS=44.212.211.226

Leave them blank and the seeder writes nothing, which is the correct behaviour for a production seed — a partner with no credentials simply never credits anyone.

Adding a partner is data, not code

Credentials live in provider_settings, dialect lives in an adapter class, and a partner with neither falls back to the config-driven GenericOfferwallAdapter. Dedicated adapters ship for BitLabs, CPAlead and Torox. Write a new adapter only when a partner's postback shape cannot be described in settings.

🔗 Step 9 — Third-Party Services (Quick Setup)

Details for each in Integrations.

▶️ Step 10 — Run the App

# 1. Backend
cd cashloop-admin-panel
php artisan serve            # http://127.0.0.1:8000
npm run dev                  # separate terminal

# 2. App — emulator, default origin (10.0.2.2 → your host)
cd cashloop-android
./gradlew :app:installDebug

# 2b. App — physical device
./gradlew :app:installDebug -Pcashloop.apiBaseUrl=http://192.168.1.42:8000/

✅ Verify Setup

Work down this list. Each line depends on the ones above it, so stop at the first failure.

📡 Remote Config Reference

That is the entire list, on purpose. Remote Config carries only what has to be settable before the app can reach the API at all — which is the API's own origin. Product configuration comes from GET /api/v1/config, where it is versioned alongside the backend that produces it.

🔌 Mobile API v1 Reference

Base URL: https://<host>/api/v1

Envelope

Every response — success or failure — has the same shape:

{
  "success": true,
  "data": { },
  "meta": { "page": 1, "per_page": 20, "total": 124, "last_page": 7, "has_more": true },
  "error": null
}

{
  "success": false,
  "data": null,
  "meta": null,
  "error": { "code": "E_CASHOUT_NOT_ALLOWED", "message": "…", "fields": { "reasons": ["…"] } }
}

error.code is stable and is what the client switches on. error.message is English and intended for logs — the app shows its own localised copy per code.

Error codes

Headers

The server keeps the user's device record current from these headers, so there is no separate "update device" call. On Android they are added by api/interceptors/ContextHeaderInterceptor.kt.

Public endpoints

Account

POST /auth/relink — claiming an abandoned guest

Sent automatically by the app, once, after a sign-in where Firebase refused to link the anonymous user because the credential already had an account. That is the only path where the server-side account changes, and without this endpoint whatever the guest earned would be stranded.

POST /api/v1/auth/relink
Authorization: Bearer <jwt of the account just signed in to>

{ "guest_refresh_token": "<the abandoned guest's refresh token>" }

→ 200 { "merged": true,  "user": { … } }   cash, coins and progression moved over
→ 200 { "merged": false, "user": { … } }   token unknown or expired — nothing to do
→ 403 E_FORBIDDEN                          refused: see below

The guest's refresh token is the authorisation. A bare user id would let any signed-in caller name someone else's account and sweep its balance into their own, so the server only merges a session the caller can prove it held. The token is consumed either way, so a replay cannot pay twice.

Home

Offers

Payout fields: payout is the boosted amount to display. original_payout and boost_percent are present only while a boost is running — the app renders the struck-through price when they are non-null and does not have to decide itself.

Partners

Wallet & cashout

Requesting a withdrawal holds the money immediately: available drops right away, cash_balance only when it is paid.

Engagement, referral, notifications, support

Quest and streak rewards are claimed, not auto-credited.

Never returned

Partner postback (not part of v1)

🗂️ Project Structure (Developers)

Android app — cashloop-android/

See Android Project Structure for the annotated tree.

Laravel admin panel — cashloop-admin-panel/

cashloop-admin-panel/
├── app/
│   ├── Domain/                 # The business logic, by area
│   │   ├── Wallet/             # WalletService — the ONLY thing that writes a balance
│   │   ├── Conversions/        # Postback → conversion → credit
│   │   ├── Providers/Adapters/ # BitLabs, CPAlead, Torox, Generic, AbstractProviderAdapter
│   │   ├── Offers/ Cashout/ Engagement/ Referrals/ Fraud/ Geo/ Layout/ Usage/
│   ├── Http/
│   │   ├── Controllers/Api/V1/ # The frozen mobile API
│   │   ├── Controllers/Admin/  # Panel screens
│   │   ├── Resources/Api/V1/   # Response shaping — what is and is not exposed
│   │   └── Middleware/         # mobile.auth, mobile.context, setLocale, staff, admin
│   ├── Models/
│   └── Support/                # Money (bcmath), ApiResponse envelope
├── database/
│   ├── migrations/             # 17 — this IS the schema
│   └── seeders/                # 22, incl. CoreSeeder and DemoSeeder
├── routes/
│   ├── api.php                 # /api/v1 + /api/postback/{provider}
│   └── web.php                 # Public site + admin panel
├── resources/                  # Blade + Livewire (admin), Inertia + React (public site)
└── README.md

Admin panel screens

🧩 Environment Configuration (Developers)

Laravel .env keys that matter

🔌 API Integration Points (Developers)

1. Laravel mobile API (REST)

Retrofit interface: api/ApiService.kt and api/AuthApi.kt. Three interceptors sit in front of it:

api/ApiCall.kt wraps every call into a Resource — success, an ApiErrorCode, or a transport failure — so no ViewModel ever sees a raw exception. api/PagedSource.kt owns paging against the meta block.

2. Firebase

• Auth — anonymous, Google, Facebook, email. The ID token is exchanged for the API JWT pair.
• Cloud Messaging — CashLoopMessagingService; the token is posted to /auth/device.
• Remote Config — one key, api_base_url.

3. Offerwall SDKs

Each launcher implements OfferLauncher and declares the slugs it handles. OfferLauncherRegistry resolves a slug to a launcher, and falls through to UrlOfferLauncher on unavailable, failed or unclaimed. Two launchers claiming the same slug is logged as a wiring mistake and the first wins — a duplicate registration must not stop a user opening an offer.

SDK credentials come from SdkConfigStore, populated from GET /providers/{slug}/sdk-config. settings is an open Map<String, String> rather than named fields on purpose: every network names its keys differently and adds new ones between releases, and typing them would mean an app release each time a partner renamed a field. A key that is absent was never configured — the server omits empty values rather than sending null, so missing and empty are the same thing.

4. Ads

ads/RewardedAdManager.kt (AdMob) and the two Unity managers. Unit ids and the daily cap come from config.ads; a network with enabled=false or no unit id is not initialised at all.

🧱 Extending and Modifying the App (Developers)

1. Add a language

1. Create res/values-xx/strings.xml and translate the keys you need — anything missing falls back to the default file.
2. Add the locale in the panel at /admin/locales/all so GET /locales offers it.
3. Translate the server-side content that the app displays: pages, email templates, offer copy.

2. Add a colour preset

1. Copy an ArcadePreset(...) block in ArcadePresets.kt, name it, and fill in every role — the data class makes the compiler check you did.
2. Add a branch to the when in active and set SELECTED.

3. Add an offerwall partner

1. Panel first. Create the provider, set its integration_type, credentials and postback allowlist. If its postback dialect fits, the GenericOfferwallAdapter handles it with no PHP at all.
2. Hosted wall? You are done — POST /providers/{slug}/open returns a tracked URL and the fallback launcher opens it.
3. Native SDK? Add the dependency to libs.versions.toml, write a launcher implementing OfferLauncher with handles = setOf("your_slug"), read its keys from SdkConfigStore, and bind it into the Set<OfferLauncher> in di/OfferwallModule.kt.
4. Return LaunchResult.Unavailable rather than throwing when a key is missing — the registry will open the web version instead.

4. Add a new home section type

1. Add the wire value to SectionLayout or SectionDataSource in data/models/HomeFeed.kt.
2. Add a branch to decodeItems and a renderer in ui/tabs/feed/SectionRenderers.kt.
3. Add the option to the panel's App sections form.
4. Old builds render the new section as nothing, which is the intended behaviour — no crash, no wrong card.

5. Add an API endpoint

1. Laravel: add the route inside the v1 group with the right throttle bucket (mobile for reads, mobile-write for anything that moves money), a controller method and an API Resource. Additive only — a breaking change goes to /v2.
2. Android: add the method to ApiService, a @Serializable model, and a repository method returning Resource<T> via apiCall { }.
3. Never bypass WalletService on the server side. If your endpoint moves money, it appends a ledger row.

Ground rules (from the backend README)

1. Every schema change is a migration. No manual SQL, ever.
2. Money is decimal(14,6) via App\Support\Money (bcmath). Never floats.
3. Never write a balance outside WalletService. Reaching for $wallet->update(...) means you wanted a ledger entry.
4. env() only in config/*.php.
5. Ledger and audit rows are immutable. Correct with a compensating entry.
6. The mobile API contract is frozen.

📊 Rate Limits and Outages

Limits key on the user where possible and fall back to IP: carrier NAT can put thousands of real users behind one address.

Service cost overview

Monitoring, in priority order

1. wallet:verify exit code. Non-zero means a balance disagrees with its ledger. Nothing else matters more.
2. Partner health. An active, configured partner sending nothing for 24 hours is the failure that raises no error and quietly stops revenue.
3. Withdrawal queue depth. Users notice this before you do.
4. Open fraud flags. They accumulate silently; nobody is paged.
5. postback_logs rejection rate. A spike usually means a partner rotated a secret or changed IPs.

Common outage symptoms

🔗 Integrations Overview

Offerwall Partners

Eight partners ship configured. Four are native SDKs, four are hosted walls opened by tracked URL. All eight pay by server-to-server postback.

Setting one up

Google AdMob

Unity Ads

Create a Unity project, enable Monetization, and copy the game id and placement ids into /admin/settings/app under the unity block. Unity Ads pulls play-services-cronet transitively, which is why the Gradle repositories are deliberately unfiltered — see Build & Run.

OneSignal & FCM

Plain FCM works independently for server-triggered, per-user messages — CashLoopMessagingService handles those, and tokens are registered through POST /auth/device.

Google & Facebook Sign-In

With Play App Signing enabled, the fingerprints that matter are the ones Play shows you under App integrity, not your upload keystore's. Add both.

Cloudflare Turnstile

Protects the website's registration, login and contact forms — not the mobile API, which is protected by Firebase token verification and rate limits. Set TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY, then enable it at /admin/settings/captcha. reCAPTCHA is supported as an alternative.

🛡 Play Policy & Permissions

Read this before you buy hardware, brand the app or plan a launch date. A rewards app of this type has three approval gates that have nothing to do with code quality, and two of them can stop you shipping regardless of how well the app works.

Permissions the app declares

Four ordinary permissions and one sensitive one. Every entry is used — the manifest carries nothing "just in case", because an unjustifiable declaration is a rejection over a feature that does not exist.

Justifying PACKAGE_USAGE_STATS

This is the one Play will ask you about directly. It is what lets the app confirm that a user actually opened and played a rewarded app, rather than installing it and immediately uninstalling it — which is the single most common way offer fraud is committed against you.

Wording you can adapt for the Play Console declaration:

You can switch this off entirely. The permission is only ever exercised for offers whose verification_mode is usage. If you run only offerwall inventory — where the partner verifies the conversion and tells you by postback — you never need it. To drop it:

1. Set no offer to verification_mode = usage in the panel.
2. Remove the PACKAGE_USAGE_STATS line from AndroidManifest.xml.

That removes the hardest approval question from your submission at the cost of one offer type. If you are launching for the first time, this is the safer path.

Incentivised installs

Rewarding users for installing other applications is permitted, but it sits in a policy area Google enforces actively, and the boundaries move. What matters in practice:

• Never reward a Play Store rating, review or ranking action. This is unambiguously prohibited and is the fastest route to suspension. The app does not implement any such offer type and you should not add one.
• Be honest in the listing. Describe it as a rewards app that pays for completing partner offers. Do not imply guaranteed earnings, "free money", or specific income figures.
• Users must actually be paid. A rewards app with unpayable thresholds or withdrawals that never complete attracts complaints, and complaints attract review.
• Ad-network rules apply on top. AdMob's own policies restrict how rewarded ads may be presented — an AdMob suspension costs you a revenue stream even if Play is content.

One product-level note: stake.png ships as a sample cashout option. Gambling-adjacent payout destinations carry their own policy weight in several markets — remove it unless you have deliberately decided otherwise.

You need your own offerwall accounts

What that means for your timeline:

• Apply to the networks early — approval is manual and commonly takes days, sometimes longer, and some decline applicants with no traffic history.
• Most will ask to see a live app or a real website before approving you. This is a chicken-and-egg problem every publisher hits; a working demo build and a real privacy policy help.
• Each approved network gives you credentials that go in the panel, not in the app. See Postbacks.
• Partner logos follow the same rule as inventory: your agreement with a network does not transfer, so treat the bundled logos as placeholders for your own approved branding.

Data safety form

Declare at minimum what the app actually collects:

A reachable privacy policy URL is mandatory. The panel serves one at /{locale}/page/privacy-policy — edit the content in Admin → Content pages and use that URL in the listing.

🔒 Security Hardening

What the app does to protect a signed-in session, and what you must not undo.

The session is encrypted at rest

The API access token and a 90-day refresh token live in the app's DataStore. That file is encrypted with AES-GCM under a key held in the Android Keystore, which never leaves the device and is hardware-backed where the device provides it.

It is applied in the DataStore serializer, so nothing else in the app has to know: SettingsCrypto encrypts on write and decrypts on read. Files written by an earlier build are plain protobuf; they are detected, read as-is and re-encrypted on the next write, so upgrading installs stay signed in.

If the file cannot be decrypted — tampering, or app data restored onto a different device — the app treats it as no session rather than crashing. The cost is one sign-in.

Backups are off

android:allowBackup="false", plus an @xml/data_extraction_rules that excludes everything from both cloud backup and device-to-device transfer. Android 12+ no longer lets allowBackup decide this alone, which is why both exist.

Cleartext traffic is disabled

usesCleartextTraffic="false". Every origin must be HTTPS, including whatever you set as the API base URL. The emulator default (http://10.0.2.2:8000/) is the one exception and it only applies to debug builds.

What the app never decides

The client measures and reports; the server decides. Rewards, balances and eligibility are computed server-side and the app acts only on the verdict, so a modified APK cannot pay itself. Every balance change is a row in wallet_transactions, and wallet:verify re-sums the ledger hourly and exits non-zero on drift.

Postbacks fail closed

A provider postback is an anonymous HTTP request whose payload says "credit this user". Every adapter refuses one unless that provider has either a shared secret it can verify or an IP allowlist. A partner configured with neither credits nobody — it does not credit them unverified. See Postbacks.

🤖 Android Release Checklist

1. Critical blockers — fix before upload

2. Release signing (keystore)

2a. Create an upload keystore (one time):

keytool -genkey -v -keystore release.jks -keyalg RSA -keysize 2048 \
        -validity 10000 -alias cashloop

2b. Tell Gradle where it is. No code change is needed — app/build.gradle.kts already reads these four values and builds the release signing config from them. Put them somewhere outside the repository:

# ~/.gradle/gradle.properties
cashloop.releaseStoreFile=/absolute/path/to/release.jks
cashloop.releaseStorePassword=…
cashloop.releaseKeyAlias=cashloop
cashloop.releaseKeyPassword=…

Or as environment variables, which is usually what you want in CI:

CASHLOOP_RELEASE_STORE_FILE       CASHLOOP_RELEASE_STORE_PASSWORD
CASHLOOP_RELEASE_KEY_ALIAS        CASHLOOP_RELEASE_KEY_PASSWORD

2c. Confirm it took effect. The filename tells you:

./gradlew :app:assembleRelease
ls app/build/outputs/apk/release/

app-release.apk            ← signed: your key was found
app-release-unsigned.apk   ← unsigned: Gradle did not see the properties

If it is still unsigned, the properties are not being read — check the path is absolute and that you edited ~/.gradle/gradle.properties, not the project's copy.

2d. Play App Signing (recommended). Let Google hold the app signing key and keep your keystore as the upload key only. If the upload key is ever lost you can reset it; the app signing key you cannot.

3. SHA fingerprints

keytool -list -v -keystore release.jks -alias cashloop

Add SHA-1 and SHA-256 to Firebase for the release key and for the Play App Signing key (Play Console → App integrity). Then re-download google-services.json. Skipping this is the single most common cause of "Google Sign-In works in debug, fails in production".

4. Versioning

Bump versionCode on every upload — Play rejects a duplicate. versionName is what users see and what X-App-Version sends, which is what the force-update gate compares against min_supported_version.

5. Build the production AAB

./gradlew clean
./gradlew :app:bundleRelease
# → app/build/outputs/bundle/release/app-release.aab

To test the exact artefact Play will serve:

bundletool build-apks \
  --bundle=app/build/outputs/bundle/release/app-release.aab \
  --output=app-release.apks \
  --mode=universal \
  --ks=release.jks --ks-key-alias=cashloop

6. Play Console

1. Create the app with your final package name.
2. Complete the store listing, content rating, target audience and Data safety form.
3. Upload the AAB to internal testing first and run the whole earn → convert → withdraw path against production.
4. Promote to production when the postback path is confirmed working on the release build.

7. Post-release

• Watch wallet:verify and the postback rejection rate for the first 48 hours.
• Keep one partner in testing as a canary when adding new ones.
• Set min_supported_version only when you genuinely need to cut off old builds — it is a hard wall for the user.

🐛 Troubleshooting

App stuck on the splash screen

The config fetch is failing. Check, in order: the origin is right and ends in a slash; the device can actually reach it (emulator ⇒ 10.0.2.2, physical device ⇒ LAN IP or tunnel); the origin is HTTPS (cleartext is disabled); the panel returns JSON for curl .../api/v1/config.

Maintenance or "update required" screen you did not expect

Both come from the server. Check maintenance_mode and min_supported_version at /admin/settings/app. Remember the gate compares against X-App-Version, i.e. your versionName.

Feeds are empty

• Is there at least one provider set to active (not testing/paused)?
• Does it have offers, and are they active and in date?
• Is the user's country blocked by a geo rule?
• Did offers:expire retire everything because the seeded demo offers had past end dates? Re-seed with DemoSeeder.

API calls fail with 401 / E_UNAUTHENTICATED

• Firebase Anonymous provider not enabled.
• FIREBASE_CREDENTIALS missing, wrong path, or pointing at a service account from a different Firebase project than the app's google-services.json.
• JWT_SECRET changed — every existing token is now invalid; users re-authenticate on next launch.

Offers open but nothing is ever credited

1. Money → Postback logs. Are hits arriving at all? If not, the partner has the wrong URL.
2. If they arrive and are rejected: the IP allowlist or the signature. A partner that rotated IPs is the usual cause.
3. If they arrive and are accepted but no conversion appears: the click id is not coming back. Confirm the app opened the URL from /offers/{id}/click rather than a store link, and that the partner's sub-id macro is in their template.
4. If a conversion exists but the balance did not move, run php artisan wallet:verify — and treat a non-zero exit as an incident.

Usage-verified offers never pay

• Usage access was not granted — it is a Settings screen the user must visit, and it cannot be granted by a normal runtime prompt.
• The offer's target package name does not match what was installed.
• The report only fires on app resume. Reopening CashLoop is required.

Withdrawal is refused

The response lists every unmet rule in error.fields.reasons. Typical causes: below min_cashout_cash; the amount exceeds available (remember pending withdrawals are already held); the option is geo-blocked or out of stock; the account carries an open fraud flag; verification is required.

Google Sign-In fails on Android

Ninety percent of the time it is one of two things: the SHA fingerprint for that build type is not registered in Firebase, or google-services.json is from a different project than the one you enabled Google sign-in on. Add both the release key and the Play App Signing key, then re-download google-services.json and rebuild.

There is no default_web_client_id to edit — the Gradle plugin generates it from google-services.json, so a stale value almost always means a stale JSON file.

Ads not showing

• A brand-new AdMob account has no fill for hours to days — test with Google's official test unit ids first.
• admob_app_id missing or malformed crashes the SDK at startup; check Logcat.
• The network is disabled or its unit id is blank in the panel — that is a deliberate "no ad slot", not a bug.

Admin panel 500s

• "Unable to locate file in Vite manifest" — public/build/ is missing or stale. Run npm install && npm run build. This takes down every page, so if nothing at all loads, check it first.
• Missing bcmath — check php -m.
• SESSION_DRIVER=database with no sessions table — run php artisan migrate.
• Stale caches after a .env change — php artisan config:clear && php artisan config:cache.
• Storage permissions — chmod -R 775 storage bootstrap/cache.

Seeding finishes but you cannot sign in to the panel

The admin was not created. AdminUserSeeder skips it — printing a warning — when ADMIN_PASSWORD is blank, is a common default, or is under 12 characters. Set a real one and re-run php artisan db:seed --class=AdminUserSeeder.

Password reset or "forgot password" pages 500

Same root cause as above: those pages are plain Blade and load the compiled stylesheet through Vite. Run npm run build.

Build issues

• JDK below 17 — settings.gradle.kts fails the build with an explicit message.
• Unresolved dependency from an ad SDK — do not add group filters to the Gradle repositories; the transitive artifacts live under unrelated group ids.
• "Kotlin plugin applied twice" — AGP 9 has Kotlin built in; the org.jetbrains.kotlin.android plugin must not be applied.
• MyChips artifact not found — its Maven repository entry in settings.gradle.kts is scoped to io.mychips; keep it.
• Last resort: ./gradlew clean && ./gradlew --stop, then File → Invalidate Caches.

❓ FAQ

Q: Do I need to import a SQL dump?
A: No — and you should not. There isn't one. php artisan migrate on an empty database builds the complete schema. The migrations are the schema, deliberately.

Q: Can I run php artisan config:cache?
A: Yes, and you should in production. Every configuration read goes through a config file and a test fails the build if a raw env() call appears elsewhere.

Q: How many Firebase Remote Config keys do I need?
A: One — api_base_url, and even that is optional if the build's baked-in origin is correct. Everything else comes from GET /api/v1/config.

Q: Where do offerwall SDK keys go?
A: In the admin panel, under the provider. They are served to the app at runtime via /providers/{slug}/sdk-config. Nothing partner-specific is compiled into the binary.

Q: How does a user get paid for an offer?
A: The app opens the tracked URL from POST /offers/{id}/click; the partner returns the click id on their postback; the server records a conversion and appends a ledger row. SDKs never credit anything.

Q: Why does the app open a Custom Tab instead of the Play Store?
A: Because the click id lives in the URL's query string, and a store intent drops it. Without the click id the conversion cannot be attributed and the user is never paid.

Q: What is the difference between cash_balance, pending and available?
A: available is what can be spent or withdrawn right now. pending is money that has arrived but is not yet withdrawable. cash_balance is the total. Requesting a withdrawal drops available immediately; cash_balance only drops when it is paid.

Q: What happens to a guest's balance when they sign in?
A: It carries over. Signing in upgrades the anonymous Firebase user in place, so the firebase_uid — and therefore the server account — is unchanged. If the credential already belongs to a different account, Firebase refuses the link and the guest session is dropped; there is no supported way to move a balance between accounts.

Q: How do I hide a whole feature?
A: Turn its flag off in config.features. The tab is removed rather than greyed out — a greyed tab still advertises something the user cannot have.

Q: Can I reorder the home screen without shipping an update?
A: Yes. Sections come from /admin/app-sections and are read on the next launch. A section with no items is omitted automatically.

Q: Which languages does the Android app ship?
A: en, tr, de, es, it, ar under res/values(-*)/, matching the locales the API serves.

Q: How do I reskin the app?
A: Change ArcadePresets.SELECTED (1–9) and rebuild. Both light and dark come from the same preset.

Q: Do I need the usage-stats permission?
A: Only if you run first-party offers with verification_mode = usage. If you rely entirely on partner offers, the permission is never exercised — and you can remove it from the manifest.

Q: Can I launch without ads?
A: Yes. Leave both ad networks disabled in the panel. The offerwall partners are the revenue engine; ads are supplementary.

Q: How do I add a partner the app has never heard of?
A: If they are a hosted wall, entirely in the panel — no app change. If they require a native SDK, add a launcher class and bind it in di/OfferwallModule.kt. See Extending.

Q: What is the one thing I should monitor?
A: The exit code of wallet:verify. Non-zero means a balance disagrees with its ledger, and nothing else in the system matters more than that.

Q: Where is support?
A: Email morningstarcode@gmail.com.