Personalized Push Notifications at Scale: Gemini 3 Pro × Firebase Cloud Messaging for Indie App Developers

Designing user segments

Personalization rests on segmentation. I keep mine to between six and ten segments along three axes — behavior × state × preference. Anything more granular and you simply cannot accumulate enough samples per group to make A/B results meaningful at solo scale.

Concrete segments from my wallpaper app:

• new_user_active: installed within three days, opened three or more times
• new_user_silent: installed within three days, opened only once
• engaged_free: opened five or more times in the last 30 days, no purchases
• engaged_paid: opened five or more times in the last 30 days, has purchased
• dormant_paid: no opens in the last 30 days, has purchased before
• dormant_free: no opens in the last 30 days, no purchases

Each segment gets its own feature payload. For engaged_paid, for example, I send the top three theme tags (nature, monochrome, abstract) the user has favorited in the last seven days, and let Gemini write copy that points to a new release matching those themes.

What you send to Gemini — and what you don't

The single most important rule first: never send personally identifiable information to Gemini. Hashed segment IDs and abstract behavioral features only. This is partly about privacy law and policy, and partly about prompt cache efficiency.

Good features (abstract, non-identifying):

• segment: engaged_paid
• top_themes: ["nature", "abstract"]
• last_active_days_ago: 2
• preferred_language: en
• recent_action_summary: saved_3_wallpapers_in_last_7_days

Bad features:

• email: user@example.com
• device_token: raw FCM token
• purchase_history: individual transaction records

Build separate prompts per locale and constrain the output with Gemini 3 Pro's responseSchema — title under 30 characters, body under 70 characters, formatted exactly so FCM can consume it directly without further parsing.

Working Cloud Functions code (Python)

This is the core of the implementation, runnable as a 2nd-gen Cloud Function. It uses google-genai for Gemini, firebase-admin for Firestore and FCM, and emits structured logs.

# main.py — Cloud Functions (Gen2) entry point
# Required packages: google-genai, firebase-admin, functions-framework
import json
import os
import logging
from datetime import datetime, timezone
from typing import Any
 
import functions_framework
from google import genai
from google.genai import types
from firebase_admin import initialize_app, firestore, messaging
 
# --- One-time init on cold start ---
initialize_app()
db = firestore.client()
client = genai.Client(api_key=os.environ["YOUR_GEMINI_API_KEY"])
 
MODEL = "gemini-3-pro"
 
# Structured output schema for the generated notification
NOTIFICATION_SCHEMA = {
    "type": "object",
    "properties": {
        "title": {"type": "string", "maxLength": 30},
        "body": {"type": "string", "maxLength": 70},
        "deep_link": {"type": "string"},
        "analytics_label": {"type": "string"},
    },
    "required": ["title", "body", "deep_link", "analytics_label"],
}
 
def build_prompt(features: dict[str, Any]) -> str:
    """Pass abstract features only — no PII reaches Gemini."""
    return f"""You write push notification copy for a wallpaper app.
Using only the segment features below, produce one notification a user will want to open.
 
Segment features:
- segment: {features['segment']}
- top_themes: {json.dumps(features['top_themes'])}
- last_active_days_ago: {features['last_active_days_ago']}
- preferred_language: {features['preferred_language']}
- recent_action_summary: {features['recent_action_summary']}
 
Constraints:
- title up to 30 chars, body up to 70 chars
- avoid imperative or hype phrasing; sincere tone
- 0 or 1 emoji (zero is fine)
- analytics_label must be "notif_<segment>_<YYYYMMDD>"
- deep_link must be "myapp://gallery?theme=<first theme>"
"""
 
def generate_message(features: dict[str, Any]) -> dict[str, Any]:
    """Call Gemini 3 Pro for a single notification payload."""
    response = client.models.generate_content(
        model=MODEL,
        contents=build_prompt(features),
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=NOTIFICATION_SCHEMA,
            temperature=0.8,
            max_output_tokens=400,
        ),
    )
    return json.loads(response.text)
 
def send_fcm(token: str, message: dict[str, Any]) -> str:
    """Dispatch via FCM HTTP v1."""
    fcm_msg = messaging.Message(
        token=token,
        notification=messaging.Notification(
            title=message["title"],
            body=message["body"],
        ),
        data={
            "deep_link": message["deep_link"],
            "analytics_label": message["analytics_label"],
        },
        fcm_options=messaging.FCMOptions(
            analytics_label=message["analytics_label"],
        ),
    )
    return messaging.send(fcm_msg)
 
@functions_framework.http
def dispatch_notifications(request) -> tuple[str, int]:
    """Cloud Scheduler entry point."""
    payload = request.get_json(silent=True) or {}
    segment = payload.get("segment", "engaged_paid")
 
    users = (
        db.collection("user_features")
        .where("segment", "==", segment)
        .where("notifications_enabled", "==", True)
        .limit(1000)
        .stream()
    )
 
    sent, errors = 0, 0
    for user_doc in users:
        features = user_doc.to_dict()
        try:
            msg = generate_message(features)
            send_fcm(features["fcm_token"], msg)
            db.collection("notifications").add({
                "user_id_hash": features["user_id_hash"],
                "message": msg,
                "sent_at": datetime.now(timezone.utc),
                "segment": segment,
            })
            sent += 1
        except Exception as e:
            logging.exception("dispatch failed: %s", e)
            errors += 1
    return f"sent={sent} errors={errors}", 200

Three things to notice. First, no PII like the FCM token ever appears in the Gemini prompt. Second, response_schema removes a class of bugs (over-length titles, missing fields) before they can break FCM dispatch. Third, every send carries an analytics_label so BigQuery can later attribute opens to specific copy.

Rate limits and retries — solo dev edition

Even on the paid tier, Gemini 3 Pro has RPM caps. Sending to 1,000 users one request at a time can take 10 to 15 minutes and may surface 429 errors mid-run. The configuration that holds up for me:

• Batch 50 users per Gemini call ("return 50 variations" inside one prompt) instead of one user per call
• On 429, exponential backoff (1s, 2s, 4s…) up to four attempts
• After max retries, write the failed user IDs to a failed_notifications collection for the next day
• Cloud Functions: 512 MB memory, 540 second timeout — comfortably inside the free tier

Batching makes individual requests slightly more expensive but slashes total cost roughly 40-50x. On the wallpaper app (about 8K DAU), my Gemini bill went from ~USD 32 a month down to ~USD 0.7 once I switched from per-user to batched generation.

Don't ask Gemini when to send

Personalize copy with Gemini, but never delegate send-time decisions to it. Timing is a probability problem; rules-based logic is more accurate and free.

A simple rule that works:

• For each user we already store the OS-reported timezone in Firestore; pick whichever of 8 a.m. / noon / 7 p.m. local is closest to the modal hour from their open-time histogram
• New users with no histogram default to 7 p.m. local
• Branch by weekday vs. weekend if you see different open-time peaks

Implement this inside the same Cloud Function and either schedule with FCM's apns.headers["apns-push-type"] = "background" for a delayed push, or hand off to Cloud Tasks with an eta timestamp.

Improving prompts via A/B tests

The whole pipeline only earns its keep if the prompts get sharper over time. The simplest A/B I keep running:

• Within a single segment, split users into prompt_v1 and prompt_v2 by the parity of the last hex digit of their hashed user ID — deterministic and trivially reproducible
• Tag each variant's analytics_label as notif_<segment>_v1_<date> / notif_<segment>_v2_<date>
• Query the Firebase-to-BigQuery firebase_messaging table and compare message_open / message_delivered
• After 7 days with at least 1,000 sends per arm, adopt the winner; otherwise design a v3

In my experience, adding constraints to the prompt outperforms loosening them. Telling Gemini "no hype, polite tone, include exactly one specific theme name" added ~0.7 points to CTR in one test on this app.

PII guardrails — what never leaves your backend

Even at indie scale this is non-negotiable. Japanese privacy law, GDPR, and Apple's App Store Review Guidelines each restrict sending user PII to AI models for training. The Gemini API contract excludes your data from training, but you should not rely on that — design so PII never leaves your backend in the first place.

Concrete implementation rules:

• Keep user_features in Firestore as aggregated behavioral counts only; raw event logs live in a separate collection
• Hash user IDs (SHA-256) before any field reaches the Gemini call
• Store fcm_token in secrets/fcm_tokens and ensure the Gemini-calling function does not read that path
• If you log Gemini request payloads, log the segment name and the list of feature keys — not the values

Apple App Review now asks pointed questions about AI usage. Being able to truthfully answer "no PII is ever sent to the model" reduces rejection risk meaningfully.

What it actually costs

Real numbers from my wallpaper app: about 8K DAU, three sends per week, 2,000-4,000 users per send.

• Gemini 3 Pro API (50-user batch × 3 sends/week × 4 weeks): ~USD 0.7/month
• Cloud Functions Gen2 (~2,000 invocations/month at ~5s each): ~USD 0.5/month
• Cloud Scheduler (4 jobs): USD 0/month (within free tier)
• Firestore reads/writes (~50,000 ops): USD 0/month (within free tier)
• FCM dispatch: USD 0/month (FCM is free)

Total: about USD 1.2/month. Lifting open rates 1.5x more than pays for that — on this single app, AdMob impressions came up by roughly USD 45/month after the rollout.

There is one reason this cost structure holds: Gemini is only doing copy generation. Segment extraction, send-time selection, and delivery itself all stay in ordinary rule-based code and managed services.

Narrowing the model's job to a single step drops the bill by an order of magnitude and makes incidents trivial to isolate. If generation fails, you fall back to the static string and the send still goes out. Hand segment logic to an LLM as well and you lose both the price and the ability to answer "why didn't this user get it?"

Pitfalls I hit so you don't have to

Pitfall 1: responseSchema maxLength is not always honored. Gemini sometimes returns a body slightly over the cap. Validate in Cloud Functions and either truncate to title[:30] or regenerate. I shipped 90-character bodies that got cut off on the iOS lock screen before I added this guard.

Pitfall 2: Stale FCM tokens accumulate fast. When messaging.send() returns UNREGISTERED, immediately delete the token from Firestore. Skip this and you'll burn 30-50 failed sends per 1,000 every campaign forever.

Pitfall 3: Emoji overflow garbles iOS notifications. Even with a "0-1 emoji" prompt constraint, Gemini occasionally returns four. I use a small regex post-processor that keeps only the first emoji.

Pitfall 4: Don't reshuffle A/B groups daily. Hash users to v1 / v2 with a fixed function and don't add the date into the hash. If users bounce between variants by day, the open-rate delta is no longer attributable to the prompt.

Observability — what to watch in BigQuery

Once the pipeline is live, the part that determines whether personalization actually pays off is your dashboard. The Firebase → BigQuery export gives you everything you need, but the default schema is verbose enough that beginners often miss the simple queries that matter.

Three queries I check every Monday morning:

-- Open rate by segment, last 7 days
SELECT
  REGEXP_EXTRACT(analytics_label, r'^notif_([^_]+)_') AS segment,
  COUNTIF(message_type = 'MESSAGE_DELIVERED') AS delivered,
  COUNTIF(message_type = 'MESSAGE_OPEN') AS opened,
  SAFE_DIVIDE(
    COUNTIF(message_type = 'MESSAGE_OPEN'),
    COUNTIF(message_type = 'MESSAGE_DELIVERED')
  ) AS open_rate
FROM `your-project.firebase_messaging.data`
WHERE _PARTITIONTIME >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY segment
ORDER BY open_rate DESC;

-- A/B variant comparison
SELECT
  REGEXP_EXTRACT(analytics_label, r'_(v\d)_') AS variant,
  REGEXP_EXTRACT(analytics_label, r'^notif_([^_]+)_') AS segment,
  COUNTIF(message_type = 'MESSAGE_OPEN') AS opens,
  COUNTIF(message_type = 'MESSAGE_DELIVERED') AS deliveries
FROM `your-project.firebase_messaging.data`
WHERE _PARTITIONTIME >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 14 DAY)
  AND analytics_label LIKE 'notif_%_v%'
GROUP BY variant, segment
ORDER BY segment, variant;

-- Stale token rate (if too high, your delete-on-UNREGISTERED logic is failing)
SELECT
  DATE(event_timestamp) AS day,
  COUNTIF(message_type = 'MESSAGE_FAILED' AND error = 'UNREGISTERED') AS stale,
  COUNTIF(message_type = 'MESSAGE_DELIVERED') AS delivered
FROM `your-project.firebase_messaging.data`
WHERE _PARTITIONTIME >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY day
ORDER BY day DESC;

I learned the third query the hard way. For about three months I had a creeping UNREGISTERED rate that never broke into the alarm threshold but quietly cost me 6-8% of effective reach. The fix was a single db.collection("user_features").document(user_id).update({"fcm_token": firestore.DELETE_FIELD}) inside the exception handler, but the lesson was: if a metric isn't on a query you actually run, it doesn't exist.

Frequency caps — protect permission, not just open rate

Once personalization starts working, the copy gets good enough that you start thinking "maybe I can send a little more often." That is the most dangerous moment in this whole system. A dip in open rate is recoverable. A user who turns notifications off is not — no amount of prompt tuning reaches someone who has revoked permission.

So I keep the frequency ceiling as a separate guard, outside the send-decision logic. The point is to put it somewhere that editing prompts or segment definitions cannot accidentally break.

from datetime import datetime, timedelta
 
# Per-segment minimum gap (days) and rolling 14-day ceiling
FREQUENCY_CAP = {
    "new_user_active": {"min_interval_days": 2, "max_per_14d": 4},
    "new_user_silent": {"min_interval_days": 3, "max_per_14d": 2},
    "engaged_free":    {"min_interval_days": 2, "max_per_14d": 5},
    "engaged_paid":    {"min_interval_days": 2, "max_per_14d": 5},
    "dormant_free":    {"min_interval_days": 7, "max_per_14d": 2},
    "dormant_paid":    {"min_interval_days": 5, "max_per_14d": 3},
}
 
def allowed_to_send(user_doc: dict, segment: str, now: datetime) -> bool:
    """Evaluate before calling Gemini so skipped users cost nothing to generate."""
    cap = FREQUENCY_CAP[segment]
    history = user_doc.get("notification_history", [])  # list of ISO8601 strings
    if not history:
        return True
 
    sent = sorted(datetime.fromisoformat(t) for t in history)
    if now - sent[-1] < timedelta(days=cap["min_interval_days"]):
        return False
 
    window_start = now - timedelta(days=14)
    recent = [t for t in sent if t >= window_start]
    return len(recent) < cap["max_per_14d"]

Running this check before the Gemini call is the part that matters operationally. Generate first and decide not to send afterwards, and you have paid for tokens nobody will ever read. On my sends, 12–18% of users are filtered out by this single function on any given run, and that generation cost simply disappears.

I append to notification_history on successful delivery and trim it to a fixed length of 15 entries, dropping the oldest. That keeps Firestore document sizes predictable and is still more than enough history for a 14-day rolling window.

One counterintuitive detail: the dormant segments get the longest minimum interval, not the shortest. Cross-referencing the dates when tokens went UNREGISTERED against the sends that preceded them, the users who had been away longest were the quickest to turn notifications off. The people you most want back are the ones you should contact least often. It reads backwards, but the data is consistent about it.

Rolling out gradually — the indie canary pattern

The first time you flip personalization on for an entire app, the temptation is to ship it to 100% of users immediately. Don't. The downside of a bad prompt is permanent — once a user disables notifications because of a weird message, they almost never re-enable. Use a 5% / 20% / 100% canary instead.

Here is the pattern I've used on three apps now:

• Day 1-3 (5% canary): route only users whose hashed ID modulo 20 equals zero through the personalization path; the other 95% still get the old generic copy. Watch open rate and notification-disable rate.
• Day 4-10 (20% canary): widen to mod 5 == 0. Continue watching the disable rate as a leading indicator.
• Day 11+ (100%): if disable rate hasn't moved, route everyone through personalization but keep the old generic copy as a 1% holdout for ongoing comparison.

The implementation is one extra check at the top of dispatch_notifications:

import hashlib
 
def in_canary(user_id_hash: str, percent: int) -> bool:
    """Stable canary by hash."""
    h = int(hashlib.sha256(user_id_hash.encode()).hexdigest(), 16)
    return (h % 100) < percent
 
# inside dispatch_notifications:
if not in_canary(features["user_id_hash"], CANARY_PCT):
    # fall back to legacy generic notification path
    send_legacy_notification(features["fcm_token"], segment)
    continue

CANARY_PCT lives in an environment variable so you can change it from the Cloud Console without redeploying. This pattern has saved me twice when a new prompt produced subtly off copy that I caught at the 5% stage instead of after a full app-wide blast.

Why I didn't pick OneSignal, Braze, or Iterable

If you read mainstream "push notification at scale" material, you'll see managed services like OneSignal, Braze, Iterable, and CleverTap. They are excellent products. They are also priced for a different audience than the indie developer.

A rough sketch of where the line falls:

• OneSignal: free tier covers up to 10K mobile users; once you cross that, AI personalization features sit on the paid Growth plan starting around USD 99/month
• Braze: priced on contact volume and not realistically accessible below mid-market budgets
• Iterable: similar to Braze, plus an enterprise sales motion
• CleverTap: pricing varies, but the AI features are bundled into higher tiers

For a solo developer running a portfolio of small-to-medium apps, the math is straightforward: you are paying USD 100+/month for features you can replicate at USD 1.50/month using the architecture in this article. The trade-off is that you do the maintenance yourself. If your time is worth more than that delta, by all means use a managed service. If you're already comfortable in Cloud Functions and Firestore, building it yourself wins on both economics and on the freedom to shape the prompts exactly to your app's voice.

I also like the philosophical shape of the DIY approach. Each notification I send is one I designed the constraints for, and the model is a junior copywriter rather than a black box. That feeling matters in solo development, where staying connected to every layer of your own product is part of what keeps the work sustainable.

Iterating on the prompt — a real before/after

Pure theory aside, here is one concrete prompt iteration I ran on the wallpaper app. The starting prompt was:

You write push notifications for a wallpaper app. Be friendly and engaging.
User segment: {segment}
Top themes: {top_themes}

Open rate after 7 days at 1,000 sends per arm: 2.1%.

The improved prompt:

You write push notification copy for a wallpaper app called Dolice.
Goal: invite the user to open the app and look at one specific theme they already love.
 
Hard constraints:
- Title: 18-26 Japanese characters or 22-30 English characters
- Body: 40-65 characters total, polite tone (です/ます in Japanese, friendly declarative in English)
- Mention exactly one theme from {top_themes} by name
- No exclamation marks, no emoji, no all-caps
- Do not promise anything (avoid "guaranteed", "best", "must-see")
- analytics_label: notif_{segment}_v2_{date}
 
Inputs:
- segment: {segment}
- top_themes: {top_themes}
- last_active_days_ago: {last_active_days_ago}
- recent_action_summary: {recent_action_summary}

Open rate after 7 days: 3.4%. The improvement came almost entirely from removing optionality. A vague "be friendly and engaging" gives Gemini too many degrees of freedom; a tight constraint set narrows the output into a band that actually matches your app's voice.

The general principle I've extracted from a dozen iterations like this: prompts get better when you remove choices, not when you add instructions. Every "do X" is a wish; every "do not Y" is a constraint that compounds. Spend more time on the negative space than the positive space.

Handling locale and time zones correctly

Personalization breaks the moment you confuse "user's preferred language" with "user's device language" with "user's timezone." For an app that ships globally, here is the order I resolve them:

1. Language for copy: prefer an explicit user setting in your app; fall back to the OS locale; fall back to English. Never infer language from country.
2. Timezone for send time: trust the OS-reported zone; cache it in Firestore; refresh it on every app open in case the user travels.
3. Currency / pricing references: treat as a separate dimension; don't bundle into language.
4. Cultural references: if your prompt allows the model to reference holidays or events, gate them by country, not by language.

A common bug is sending Japanese push to a Japanese-language user living in Brazil at 7 a.m. Brasília time, which is 7 p.m. JST — the user wakes up to a notification timed for someone else. Always personalize the time using the user's actual zone, not your assumption about it.

Maintenance cadence — what I actually do each week

Personalization is not a "ship it and forget it" feature. The cadence I keep on each app:

• Daily (automated): dispatch jobs run on schedule, BigQuery export updates overnight
• Monday morning (manual, ~15 min): open the three SQL queries above; eyeball segment open rates and the stale token chart
• Every two weeks (manual, ~30 min): review the lowest-performing segment; either change the prompt or merge it into a sibling segment if it never recovered
• Quarterly (manual, ~2 hours): rotate prompt versions; archive old notifications Firestore docs older than 90 days; re-baseline the open-rate target

The total ongoing time investment is small once the pipeline is in place — maybe an hour a week across all apps. That's well within what a part-time indie can sustain alongside building new features.

Edge cases worth designing for up front

Three categories of edge case routinely cost solo developers a weekend if they are not handled in the initial implementation.

Time-shifted users. If your app has users who travel internationally — common for productivity, photography, and travel apps — the cached timezone in Firestore can be days behind reality. Add a lightweight check on every app launch: if Intl.DateTimeFormat().resolvedOptions().timeZone differs from the cached value, write the new zone immediately. Without this, your "send at 7 p.m. local" rule will misfire for exactly the most engaged segment of users.

Notification permission revocations. iOS and Android both let users silently disable notifications without uninstalling. The first you'll know about it is that opens flatten while deliveries continue. Track permission_status separately from notifications_enabled (the former comes from the OS, the latter from your app's own opt-in flow). When permission_status flips to denied, stop generating personalized copy for that user — there is no point spending Gemini tokens on someone who will never see the result.

Daylight saving transitions. This one bit me on a US-targeted app. The OS-reported timezone identifier (America/Los_Angeles) handles DST correctly, but if you're storing a UTC offset (-08:00) and computing send times, you'll send everything an hour off twice a year. Store IANA timezone IDs, not UTC offsets, and let the standard library handle the math.

Why this approach works for non-wallpaper apps too

The wallpaper app made a convenient case study because the segment features are simple (themes, save count, paid status). The same architecture transfers to other categories with minor adjustments to the feature payload:

• Productivity / habit tracking apps: features become streak_length, last_completion_days_ago, top_categories. Gemini writes encouragement that matches the user's actual habit pattern instead of generic "Time to log your day!" copy.
• News / content apps: features become top_topics, articles_read_this_week, preferred_format (long form vs. short). The model produces headlines pointing to specific articles without you hard-coding per-topic templates.
• Fitness apps: features become last_workout_days_ago, goal_type, intensity_preference. The same caveat about not over-promising results applies — keep "guaranteed" out of the constraint set.
• Marketplace apps: features become last_browsed_category, cart_abandonment_status, seller_or_buyer_role. Gemini handles the gentle reminder copy you'd otherwise hard-code into 12 different SQL branches.

In every case, the architecture diagram doesn't change. What changes is the shape of the segment features, the constraints in the prompt, and the analytics labels you slice on. That portability is part of why I keep using this pattern across my whole portfolio rather than adopting a managed service per app.

One thing to do next

Thank you for reading. Before automating anything, hand-write five personalized notifications using your own data, send them, and ask yourself "would I open this?" Get your gut calibrated against your app's voice first. When you do switch to automation, you'll feel like the supervising editor of every send rather than a passive recipient of model output — and that's the difference between a system that lasts a quarter and one that lasts years.

For deeper dives, the Gemini API × Cloud Tasks Async Job Queue Production Guide and the Gemini API Rate Limiting & Quota Management Production Guide pair well with this architecture.

I'm still tuning the personalization on my own apps. The shape of the audience is different in every product, so the configuration described here is a starting point, not an answer. If you ship this and discover a better pattern, I'd love to learn from your run.