Connect your app's users

Your app keeps its users in a Firestore collection of its own. Point Arc CMS at it, and Arc CMS can email those people, group them in live lists and start sequences when their data changes, while the data stays where it is.

This page is the walk-through. What each screen does, what is stored and who can use it are in App audience.

Which case is yours

What Arc CMS keeps. The people in your collection are not Arc CMS users: they get no users record and never sign in to Arc CMS. Arc CMS stores only its own facts about each of them (email consent and sequence progress) in AppAudience, under a hash of their unique key. No profile data is copied.

Check that your collection fits

• One top-level collection, one document per person, such as users/{id}. Not a subcollection or a collection group.
• A unique key per person: the document id, or a field such as uid, email or phone that no two people share. An app with phone sign-in may have no email, so do not assume it.
• An email field, for anyone Arc CMS should email. People without one are listed but never emailed.
• At most 2000 people. Lists, counts and broadcasts read the whole collection, up to 2000 documents, and the admin is told when it is cut short.
• The features: audience on for all of this, and email-marketing on for broadcasts and sequences. Both are on unless src/custom/features.ts turns them off.

Connect it

1. Point Arc CMS at the collection. The database is almost always (default); the path is the collection and a wildcard, exactly <collection>/{id}:

   npm run arc:configure -- --project=default --app-users-database='(default)' --app-users-path='users/{id}'

   This writes ARC_APP_USERS_DATABASE and ARC_APP_USERS_PATH into functions/.env.{projectId}. Add --dry-run to see the changes first. If you set the project up with the guided npm run deploy and named the other app's collection there, this is already done.

2. Deploy the functions. The trigger that watches your collection is bound when it is deployed, so a changed path always needs a deploy:

   npm run deploy -- --only functions --project default

3. Tell Arc CMS how to read a person in Settings, App audience. The top shows the database and collection you deployed. Then choose:

   Setting	Choose
   Unique key	The document id, or the field that identifies one person
   Email field, Phone field, Name field	The fields that hold them. Fields are offered from a sample of real documents; nested ones are written as dot paths such as profile.name.
   Watch for changes	The fields whose changes should start something, such as isPro or plan.tier. Leave out counters and timestamps: they change all the time and mean nothing.

   Use "Test with a document" to see one person as Arc CMS reads them, then Save. This needs no deploy and can change at any time.

4. Check the connection. Audience, App users lists your people with their names and addresses. Open one, change a watched field in your app (or in the Firebase console), and the change appears under their recent activity.

Email people when something changes

Settings, Automations lists the events your collection produces:

1. Create the email template first. It can use the person's own fields as ##APP.<field>##, with a fallback after a bar: ##APP.plan.tier|free##. All tags are in Email merge tags.

2. In Settings, Automations, switch the event on and add a rule: a name, for a field change an optional condition on the old and the new value, and the email to send (transactional reaches everyone; marketing respects unsubscribes).

3. Change the field in your app and check the person's recent activity and Email Logs.

Values compare as text, ignoring case, and a missing field counts as empty: isPro becoming true is "becomes exactly true". These rules only send emails; the people are not contacts, so rules never add them to ordinary lists.

Group them and send to them

• Live list: Audience, Lists, create a list and choose "App users (live)". Add conditions on your fields (is, is not, is any of, contains, is greater than, is less than, is empty, is not empty); a person must match them all. Nobody is stored: the list is worked out from your collection each time.
• Broadcast: pick the live list in Broadcasts. Each person gets the email with their own ##APP.*## values, and an address that is on two lists gets it once.
• Sequence: a drip campaign on a live list. A person joins when a change makes them start matching, and leaves when they stop matching, are deleted, or unsubscribe. Switch on "Enroll existing members on activate" to include everyone who matches when you activate it.

Unsubscribing: everyone starts subscribed. The unsubscribe link and the preferences page record the choice in AppAudience and end their sequences; it shows in Audience, App users.

Your own Arc CMS users

An app built on Arc CMS, with people signing up to it, can use the same live lists, automations and sequences over its own users. A project set up with the guided npm run deploy as "Only by Arc CMS" already has this; otherwise run:

npm run arc:configure -- --project=default --app-users=own

npm run deploy -- --only functions --project default

• Settings, App audience starts with the fields filled in: the document id as the key, and email, phone and name. Add the fields to watch.
• These people are also contacts, on the "All Users" list. An address on an ordinary list and a live list gets a broadcast once, and a contact's unsubscribe applies to both.
• One sign-up fires two events, user.signed_up and app_user.created. Put a welcome email on one of them, not both.

What the other app does

Nothing changes in it. Tell its developers:

• Keep writing user documents as you do. Keep the email field current: Arc CMS reads it at every send.
• Deleting a user document ends their sequences; their unsubscribe is kept in case the address comes back.
• Never write to the Arc CMS database, and never store a secret under a name that does not look like one.

Changing things later