> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/notifications/marketing-popups.md).

# Marketing popups

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/marketing-popups.md).
{% endhint %}

Snapfix staff announce features and offers with **marketing popups**: a picture and, when the popup has a link, a "Tell me more" button. Staff set each popup up in the admin app, for all **sites** or chosen ones, per platform, optionally for one language, with campaign dates and a time window for each weekday. The web shows popups on the Fix page and the apps on the **group list**. Each person sees a popup once on each device or browser.

## Rules

### Setting up popups

* Staff create, change and delete popups on the admin app's "Marketing Popup" page: a name, a portrait and a landscape image, an optional link, the sites, the platforms, a language and country, the campaign dates in the popup's time zone, the weekday windows and an active switch. The fields and their rules are in [Marketing popup (admin app)](https://docs.snapfix.com/how-the-apps-work/screens/staff/marketing-popups.md#create-or-edit-marketing-popup).
* Anyone signed in to the admin app can change any popup: the page checks only for a session, and the popup calls check no staff flag.
* A popup with no sites picked goes to every site ([Marketing popup (admin app)](https://docs.snapfix.com/how-the-apps-work/screens/staff/marketing-popups.md#create-or-edit-marketing-popup)).

### Which popups a person can get

* The server returns the popups that are active, not deleted, aimed at the site or at every site, and inside their campaign dates. It does not check the weekday windows, and it sets no order ([`GET /v1/app/parents/{uuid}/popups`](https://docs.snapfix.com/engineering-reference/api/notifications.md#get-v1appparentsuuidpopups), [`get_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-actionget_mkt_popup); api\_php\_live\_v2 @ ef3c4319f6, `app/Services/ParentService.php:425-433`).
* Any signed-in user can read any site's popups.
* Each app then skips a popup that is switched off for its platform, already seen on this device, outside today's window, or for another language, and shows the first one left ([Marketing popup object](https://docs.snapfix.com/engineering-reference/api/notifications.md#marketing-popup-object)).
* A weekday with no window gets no popup. The window is read on the viewer's own clock, not in the popup's time zone \[[ASK-167](https://github.com/snapfix/docs/blob/main/ASK.md#ask-167-should-a-marketing-popups-daily-window-follow-the-popups-time-zone)] (web\_app\_v2 @ 0989b8e685, `src/app/services/marketing-popup/marketing-popup.service.ts:56-67`; ios @ aa31967ac8, `SnapFix/MarketingPopupManager.swift:118-150`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/GroupListingFragment.java:1293-1341`).
* A popup with no language shows in every language. With one, the web matches it against the browser's languages and Android against the device's language tag, ignoring case. iOS compares it exactly with the system's sorting identifier, which may have another form, so whether such a popup ever reaches an iPhone needs a device check \[[ASK-168](https://github.com/snapfix/docs/blob/main/ASK.md#ask-168-does-a-language-targeted-marketing-popup-reach-ios-users)] (`marketing-popup.service.ts:69`; `MarketingPopupManager.swift:183-199`; `GroupListingFragment.java:1247-1255`).

### When a popup shows

* **Web:** on the Fix page, once the browser is idle after the page loads, and again when the site changes there. It checks at most once every five hours, with one timer for every site (`src/app/pages/fix/fix.component.ts:278`, `:300-317`; `marketing-popup.service.ts:103-112`; `src/app/shared/config.ts:117`).
* **iOS:** each time the group list loads (ios @ aa31967ac8, `SnapFix/BusinessListingVC.swift:156`).
* **Android:** when the group list shows, once per app start, again after sign-out and when the tooltip tour ends (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/MyApplication.java:78`, `GroupListingFragment.java:317-318`). Without a connection it does not check (`GroupListingFragment.java:1192-1194`).
* Each check shows at most one popup. The others wait for a later check.

### What the popup shows

* **Image:** the web shows the portrait image in windows under 600 pixels wide and the landscape image otherwise, and tries the other one when the first does not load. The apps show the portrait image when there is one, else the landscape image (`marketing-popup.service.ts:54`, `:123-140`; `MarketingPopupManager.swift:60-61`; `GroupListingFragment.java:1344-1352`).
* **No image:** the web skips a popup whose images do not load and tries the next one. iOS skips a popup without an image link; when the chosen popup's image does not load, the apps show nothing at that check (`marketing-popup.service.ts:71-73`; `MarketingPopupManager.swift:60-70`, `:105-111`).
* **"Tell me more":** shown only when the popup has a link. It opens the link in a new tab on the web, and outside the app on iOS and Android (`src/app/components/marketing-popup-dialog/marketing-popup-dialog.component.html:10-16`; `SnapFix/MarketingPopupVC.swift:100-105`; `app/src/main/java/gmail/com/snapfixapp/bottomSheet/MarketingMessageBottomSheet.kt:79-90`).
* **Closing:** the close button closes it. On iOS, tapping outside or dragging does not (`MarketingPopupVC.swift:14-19`).

### Seen popups

* A popup a person has seen is kept per person on the device or in the browser, so it can show again on another device or after a reinstall. The web marks it seen when the dialog closes; the apps when it shows, even if it is never closed (`marketing-popup.service.ts:84-95`; `MarketingPopupVC.swift:77`; `MarketingMessageBottomSheet.kt:54-61`; `app/src/main/java/gmail/com/snapfixapp/utils/MarketingPopupDataManager.kt:45-59`).
* The apps log show, click and close events for each popup (`MarketingMessageBottomSheet.kt:68-82`; `MarketingPopupVC.swift:52`, `:100-110`).

### Limits and plans

* No plan or role limits who sees a popup, beyond the site, platform and language targeting.

## Flow

```mermaid
flowchart TD
  setup["Staff set up a popup in the admin app"] --> check["A check runs: Fix page on the web, group list on the apps"]
  check --> gate{"Web: checked less than 5 hours ago?"}
  gate -- yes --> none["Nothing shows"]
  gate -- no --> live["Server returns the site's live popups"]
  live --> pick{"Platform on, not seen, today's window, language matches?"}
  pick -- "none left" --> none
  pick -- "first match" --> image{"Image loads?"}
  image -- "no, web" --> pick
  image -- "no, apps" --> none
  image -- yes --> show["Shows one popup, with Tell me more when it has a link"]
  show --> seen["Marked seen for this person on this device"]
```

## Platforms

| Capability           | Web                                                                     | iOS                                                                                                                                                                    | Android                                                       |
| -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Where it shows       | A dialog on the Fix page                                                | A panel over the group list                                                                                                                                            | A bottom sheet over the group list                            |
| When it checks       | Fix page, at most every five hours                                      | Each time the group list loads                                                                                                                                         | Once per app start, after sign-out and after the tooltip tour |
| Image                | Portrait under 600 pixels wide, else landscape; falls back to the other | Portrait when set, else landscape                                                                                                                                      | Portrait when set, else landscape                             |
| Language match       | The browser's languages                                                 | Exact match with the system identifier \[[ASK-168](https://github.com/snapfix/docs/blob/main/ASK.md#ask-168-does-a-language-targeted-marketing-popup-reach-ios-users)] | The device's language tag, ignoring case                      |
| Weekday window       | The browser's clock                                                     | The device's clock                                                                                                                                                     | The device's clock                                            |
| Marked seen          | When closed                                                             | When shown                                                                                                                                                             | When shown                                                    |
| Without a connection | Nothing shows                                                           | Nothing shows                                                                                                                                                          | No check                                                      |

## Screens

* [Marketing popup (admin app)](https://docs.snapfix.com/how-the-apps-work/screens/staff/marketing-popups.md): where staff create, change and delete popups.
* [Fix](https://docs.snapfix.com/how-the-apps-work/screens/tasks/fix.md): where the web shows a popup.
* [Group list](https://docs.snapfix.com/how-the-apps-work/screens/groups/group-list.md): where the apps show a popup.

## API and data

* [`GET /v1/app/parents/{uuid}/popups`](https://docs.snapfix.com/engineering-reference/api/notifications.md#get-v1appparentsuuidpopups): the web's list of a site's live popups. [`POST ?action=get_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/notifications.md#post-actionget_mkt_popup): the same list for the apps. The fields are in the [Marketing popup object](https://docs.snapfix.com/engineering-reference/api/notifications.md#marketing-popup-object).
* Staff actions: [`admin_list_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_list_mkt_popup), [`admin_mkt_popup_detail`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_mkt_popup_detail), [`admin_create_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_mkt_popup), [`admin_modify_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_modify_mkt_popup) and [`admin_delete_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_delete_mkt_popup).
* Tables: [`mkt_popup`](https://docs.snapfix.com/engineering-reference/db/tables/mkt_popup.md) holds the popups, their sites (`parent_uuid_json`), platform switches, dates, time zone and weekday windows.

## Depends on

* [Groups](https://docs.snapfix.com/product/features/groups/groups.md): the group list, where the apps show popups.
* [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md): a popup is for the selected site.
* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): on Android, signing out lets the check run again.
* [Staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md): where staff set popups up.
* [Feedback surveys](https://docs.snapfix.com/product/features/notifications/feedback-surveys.md): the web's Fix page asks for its survey at the same moment.

## Edge cases

* **Several sites:** a site switched to within five hours of the web's last check, or later in the same Android run, waits for a later check.
* **Several live popups:** the server sets no order, so staff cannot choose which shows first.
* **Time zones:** the campaign dates follow the popup's time zone, the weekday windows the viewer's clock \[[ASK-167](https://github.com/snapfix/docs/blob/main/ASK.md#ask-167-should-a-marketing-popups-daily-window-follow-the-popups-time-zone)].
* **Popup without a time zone:** the admin app's edit dialog breaks on it.
* **Another device:** a popup seen on one device can show again on another.
* **Offline:** Android skips the check; the web and iOS show nothing when the request fails.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/notifications/marketing-popups.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
