Android Reward Collection Agent

-

 

Android Reward Collection Agent

Goal

Build an Android AI UI navigator that can complete routine, allowed app tasks such as:

  1. Open selected Android apps or games.
  2. Claim daily login rewards.
  3. Claim new event login rewards when they appear.
  4. Click a configured button once every 24 hours, like the daily action in Pi Network or Bee Network.
  5. Record each run in a dashboard with status, screenshots, timestamps, and the next scheduled run time.

This plan intentionally avoids bypassing anti-cheat, captchas, account protections, purchases, rate limits, or anything that violates app rules. The agent should behave like a user following the visible UI.

Recommended architecture

1. Controller layer

Use a small backend service as the scheduler and brain.

Recommended stack:

  • Python backend, FastAPI.
  • SQLite first, Postgres later if needed.
  • APScheduler or Celery beat for scheduled 24 hour runs.
  • Playwright only for the web dashboard, not for Android control.
  • Android control through an automation adapter.

The controller stores:

  • Apps to automate.
  • Reward tasks per app.
  • Last successful claim time.
  • Next allowed run time.
  • Screenshots before and after each run.
  • Step logs and failures.
  • Human-readable status for the dashboard.

2. Android automation adapter

Support both real Android phones and emulators with the same high-level task interface.

Option A, real phone

Use either:

  • Android Accessibility Service inside a companion app, best for reliable tapping, text detection from UI hierarchy, and long-running phone automation.
  • ADB from a trusted PC/server, simpler to prototype but less seamless for an everyday phone.

For the real phone path, I recommend starting with ADB for prototyping, then moving stable flows into an Accessibility Service if you want the agent to run directly on-device.

Option B, emulator

Use:

  • Appium + UiAutomator2 for structured element lookup.
  • ADB fallback for screenshots, taps, swipes, app launch, and OCR-based fallback.

The emulator is best for always-on scheduled collection because it can run on a PC or cloud machine without interrupting your phone.

3. Agent execution model

Do not let the AI blindly tap the screen. Use a constrained state machine with AI only as a fallback interpreter.

Each app gets a task recipe like:

app_id: pi_network
package_name: com.blockchainvault
schedule: every_24_hours
success_condition: "button clicked and countdown/next mining time visible"
steps:
  - launch_app
  - wait_for_home
  - close_known_popups
  - find_claim_or_mine_button
  - tap_button
  - verify_success
  - capture_after_screenshot

For games with daily rewards:

app_id: example_game
package_name: com.example.game
schedule: daily
success_condition: "daily reward screen shows claimed or no claim button remains"
steps:
  - launch_app
  - wait_for_loaded_screen
  - close_known_popups
  - open_rewards_menu_if_needed
  - claim_daily_login_reward
  - claim_event_login_reward_if_present
  - verify_success
  - capture_after_screenshot

4. UI perception strategy

Use a three-level recognition system, from most reliable to least reliable.

Level 1, Android UI hierarchy

Read visible UI elements through Appium or Accessibility APIs:

  • Text labels.
  • Content descriptions.
  • Button bounds.
  • Package/activity state.
  • Clickable elements.

Use this whenever possible because it is stable and avoids relying on screenshots.

Level 2, template and OCR fallback

When the app or game renders custom UI that does not expose useful accessibility labels:

  • Take a screenshot.
  • Run OCR to find visible text like “Claim,” “Daily,” “Collect,” “Start,” “Mine,” “24h,” “Reward,” “Event.”
  • Use image templates for stable icons/buttons if needed.
  • Tap the center of the matched region.

Level 3, AI fallback with guardrails

Use an LMM only when the deterministic rules cannot identify the current screen.

The AI should return a structured action only, for example:

{
  "screen_state": "daily_rewards_popup",
  "recommended_action": "tap",
  "target_label": "Claim",
  "target_box": [420, 980, 650, 1060],
  "confidence": 0.82,
  "reason": "Visible reward popup has a Claim button"
}

Guardrails:

  • Only allow actions from an approved list: tap, swipe, back, wait, screenshot, launch_app.
  • Never allow purchase, captcha solving, password entry, changing account settings, or sending messages.
  • Stop and ask for manual review if confidence is low or if a sensitive screen appears.

Dashboard design

Dashboard pages

  1. Overview

    • App name.
    • Last run status.
    • Last successful claim time.
    • Next scheduled run.
    • Device/emulator status.

  2. Task history

    • Each run with timestamp.
    • Success, failed, skipped, or needs review.
    • Step-by-step log.
    • Before and after screenshots.

  3. App configuration

    • Package name.
    • Schedule interval.
    • Claim keywords.
    • Event reward keywords.
    • Success condition.
    • Retry count.

  4. Manual review

    • Shows screenshot when automation is unsure.
    • Lets you approve a suggested tap or mark the task complete.

Run statuses

Use these statuses:

  • success: reward or 24 hour button was claimed.
  • already_claimed: the app says the reward is not available yet.
  • skipped: the 24 hour timer has not elapsed.
  • failed: app could not be opened, screen did not load, or success could not be verified.
  • needs_review: agent found an unknown popup, captcha, login screen, purchase screen, or low confidence action.

Scheduler logic

For every task:

  1. Check next_run_at.
  2. If current time is earlier, skip.
  3. Start device session.
  4. Launch target app.
  5. Execute the task recipe.
  6. Verify success.
  7. Save screenshots and logs.
  8. Set next run time.

For 24 hour button apps:

  • Use the last success time plus 24 hours as the default next run.
  • If the app shows a countdown, parse it and update the next run time from the countdown.
  • Add a small safety buffer, for example 5 to 15 minutes, to avoid tapping too early.

Failure handling

The agent should retry only safe actions.

Recommended retry behavior:

  • App launch: retry 2 times.
  • Network/loading wait: wait up to a configured timeout.
  • Popup close: try known close buttons, then screenshot review.
  • Claim button not found: check if already claimed, then mark already_claimed or needs_review.
  • Login required: stop, mark needs_review.
  • Captcha or anti-bot challenge: stop, mark needs_review.
  • Purchase/payment screen: stop, mark needs_review.

Data model

Tables:

devices

  • id
  • name
  • type, real_phone or emulator
  • adb_serial
  • status
  • last_seen_at

apps

  • id
  • display_name
  • package_name
  • enabled
  • device_id

tasks

  • id
  • app_id
  • task_type, daily_reward, event_reward, 24h_button
  • schedule_type
  • interval_hours
  • next_run_at
  • success_condition
  • recipe_json

runs

  • id
  • task_id
  • started_at
  • finished_at
  • status
  • summary
  • before_screenshot_path
  • after_screenshot_path
  • next_run_at

run_steps

  • id
  • run_id
  • step_name
  • status
  • message
  • screenshot_path
  • created_at

Implementation phases

Phase 1, prototype on emulator

Build a proof of concept with one app first.

Deliverables:

  • FastAPI backend.
  • SQLite database.
  • Appium or ADB connection to emulator.
  • Launch app.
  • Take screenshots.
  • Tap configured button by text, content description, OCR, or fixed fallback coordinate.
  • Dashboard showing run history.

Phase 2, add task recipes

Add reusable recipes:

  • Daily login reward claim.
  • Event login reward claim.
  • 24 hour button click.
  • Popup closing.
  • Success verification.

Phase 3, add real phone support

Add a device adapter abstraction:

class AndroidDevice:
    def launch_app(self, package_name): ...
    def screenshot(self): ...
    def get_ui_tree(self): ...
    def tap(self, x, y): ...
    def swipe(self, start, end): ...
    def back(self): ...

Implement adapters for:

  • AdbDevice
  • AppiumDevice
  • later, AccessibilityDevice

Phase 4, improve reliability

Add:

  • Per-app screen state detection.
  • OCR fallback.
  • Template matching fallback.
  • Manual review queue.
  • Better countdown parsing.
  • Notification on failure.

Phase 5, production hardening

Add:

  • Encrypted secrets.
  • Device health checks.
  • Run cooldowns.
  • Per-app rate limits.
  • Screenshot retention policy.
  • Exportable logs.
  • Optional remote dashboard auth.

Output contract

Each completed run should produce a dashboard entry with:

{
  "app": "Pi Network",
  "task": "24h_button",
  "status": "success",
  "started_at": "2026-06-10T15:00:00Z",
  "finished_at": "2026-06-10T15:00:31Z",
  "summary": "Opened app, tapped daily button, verified next countdown.",
  "next_run_at": "2026-06-11T15:10:00Z",
  "screenshots": {
    "before": "/screenshots/run_123_before.png",
    "after": "/screenshots/run_123_after.png"
  }
}

What not to automate

The agent should stop and require manual review for:

  • Captchas.
  • Password or seed phrase prompts.
  • Purchases or payment screens.
  • Anti-cheat warnings.
  • Account recovery screens.
  • Anything that asks for irreversible confirmation.

Recommended first build target

Start with an emulator and one 24 hour button app, then add a game daily reward flow after the dashboard and scheduler are stable. This reduces risk because the 24 hour button task is simpler than event reward navigation.

Comments

Post a Comment