getting-started

PushFire — Getting Started

When to use this

Use this skill when a developer is new to PushFire, needs the entity model (project, subscriber, device, tag, segment, workflow, broadcast), or is choosing between the Flutter SDK, Node.js client, and REST API. Do not use it for raw FCM/APNs-only setups with no PushFire project.

What is PushFire

Push notification and email automation platform. Manages subscribers, devices, tags, segments, workflows, and broadcasts — all scoped to a project.

---

Core Entities

Project

Isolated workspace. Stores audience data, messaging automations, delivery configuration, and team access.

• Created with Firebase credentials (Service Account JSON) for push delivery
• Has a Pushfire ID (project UUID) for API calls
• Plan & billing managed by Owner

Subscriber

End user tracked inside a project. The unit workflows and broadcasts operate on.

• externalId — your app's user identifier (optional, set on login)
• name, email, phone — profile and contact fields
• metadata — arbitrary JSON (strings, numbers, booleans, nested objects)
• tags & segments — audience membership for targeting
• States: anonymous (device-only) or identified (logged in with externalId)

Device

FCM token + platform info attached to a subscriber. One subscriber can have multiple devices.

• Platforms: Android, iOS, Web, Desktop, Other
• fcmToken — Firebase Cloud Messaging token
• pushNotificationEnabled — whether device accepts push
• lastActiveAt — last activity timestamp

Tag

Named label attached to subscribers. Powers segments, workflow conditions, and broadcast targeting.

• Types: Custom (user-created) or Default (system, read-only)
• Value: Optional string/number associated with the tag
• Operators: Exists, NotExists, Equals, NotEquals, Contains, NotContains, GreaterThan, LessThan

Segment

Rule-based audience group computed from tag conditions. Not uploaded — computed by PushFire.

• Types: Custom or Default (read-only)
• Usage: Audience targeting, broadcast targeting, workflow Entry Segment triggers
• Sync: syncSubscribers keeps membership updated automatically

Workflow

Visual automation built in a graph editor. Trigger types: Entry Segment (auto) or Manual (API).

• Nodes: Start, Wait, Condition, Push Notification, Email Notification, Join, End
• Versioned: Edits create new version, history preserved
• Execution: Per-subscriber node tracking with status lifecycle

Broadcast

One-off push or email campaign without a workflow graph. Target by tag, segment, or specific subscribers.

• Status lifecycle: Pending → InProgress → Completed (or Failed/Retrying)
• Email requires: Connector + sender + published layout + subject + body

Connector

Links PushFire to external delivery providers.

• Email: Resend (available now); Mailchimp, SendGrid coming soon
• SMS: Twilio (coming soon)
• Has encrypted credentials, domain config, senders, and active/inactive flag

Email Layout

Reusable HTML header + footer under Emails → Layouts. Must be published before use.

---

Roles

Role	Access
Owner	Full access including Payment & Billing
Editor	Messaging, audience, connectors, developers, general settings
Viewer	Read-only dashboards, broadcasts, audience lists

Console Sections by Role

• Getting Started, Overview, Messaging, Audience — all roles (Viewers read-only)
• Connectors, Emails, Developers — Owner and Editor
• Settings → General — Owner and Editor
• Settings → Payment & Billing — Owner only
• Settings → Members — all roles (Viewers cannot invite/change roles)

---

Inbound vs Outbound

Direction	What	How
Inbound	Subscribers, devices, tags, events enter PushFire	SDK or REST API (Integrations)
Outbound	Push notifications and emails delivered to audience	Firebase (push), Connectors (email)

---

Create Your First Project

1. Sign up at PushFire Console
2. Create a project — name, description
3. Upload Firebase Service Account JSON (Settings → General)
4. Follow the Getting Started checklist in the console
5. Copy API Token from Developers → API Token
6. Integrate via Flutter SDK, Node.js SDK, or REST API

---

Integration Flow

1. Authenticate — Bearer token from Developers → API Token
2. Register devices — attach FCM tokens via SDK or POST /register-device
3. Login subscribers — identify users with externalId via SDK or POST /login-subscriber
4. Assign tags — label subscribers for segmentation
5. Verify — check Audience → Subscribers in the console
6. Send — workflows, broadcasts, or API messages

---

What Integration Does NOT Do

• Firebase credentials enable push delivery — they don't import subscribers automatically
• Segments are computed from tag rules — not uploaded as separate entities
• Do not follow legacy Firebase + FlutterFlow sync guides — use current Integrations docs