> 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/how-the-apps-work/screens/staff/marketing-popups.md).

# Marketing popup

{% 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)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/staff/marketing-popups.md).
{% endhint %}

Staff create, change and delete the marketing popups that the iOS and Android apps and the web app show to users: two images, a link, a campaign period, the platforms and sites a popup goes to, and a weekly schedule.

* **Where:** admin app `/marketing-popup`; menu "Marketing Popup"
* **Who:** anyone signed in to the admin app ([Access](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)). The popup calls check no staff flag, so any signed-in user can publish, change or delete the popups every site sees ([`admin_create_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_mkt_popup)).
* **Feature:** [Marketing popups](https://docs.snapfix.com/product/features/notifications/marketing-popups.md)

## Layout

1. **Title.** "Marketing Popup", then a round "+" button with the text "Create a new Marketing Popup".
2. **Table.** The popups that are not deleted, active or not, newest first. 10 rows per page by default (10, 20, 50 or 100), with a quick jump box. Columns:
   * "Name": a search box and a sort; the name is cut to the column width, with the full name in a tooltip.
   * "Start Date" and "End Date": the campaign dates in the popup's own time zone, as `YYYY-MM-DD`.
   * "IOS", "Android" and "Web": "Enabled" or "Disabled".
   * "Image Portrait" and "Image Landscape": a round preview button. The table loads each image when the list arrives; the button spins meanwhile, then shows a warning icon with the tooltip "Image not found" when the image does not load, or the tooltip "Preview".
   * "Active": "Yes" or "No".
   * "Action", pinned to the right: an edit button (tooltip "Edit") and a delete button (tooltip "Delete").

## Inputs

| Field       | Type                             | Required | Default | Rules and messages                                                                                                        |
| ----------- | -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| Name search | Text, in the column's search box | No       | Empty   | Keeps the loaded rows whose name contains the text, ignoring case. The box says "Search name", with "Search" and "Reset". |

The popup's own fields are in [Create or Edit Marketing Popup](#create-or-edit-marketing-popup).

## Actions

| Action           | Who              | What happens                                                                                                                                                                                                                | API                                                                                                                                    |
| ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Open the page    | Anyone signed in | Lists the popups.                                                                                                                                                                                                           | [`POST ?action=admin_list_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_list_mkt_popup)     |
| "+"              | Anyone signed in | Opens [Create Marketing Popup](#create-or-edit-marketing-popup). Disabled while a delete runs.                                                                                                                              | None                                                                                                                                   |
| Edit             | Anyone signed in | Opens [Edit Marketing Popup](#create-or-edit-marketing-popup) and loads the popup. Disabled while a delete runs.                                                                                                            | [`POST ?action=admin_mkt_popup_detail`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_mkt_popup_detail) |
| Preview an image | Anyone signed in | Opens the image full size. Does nothing while the image is still loading, or after it failed.                                                                                                                               | None                                                                                                                                   |
| Delete           | Anyone signed in | After the confirmation "Are you sure you want to delete the item?" and "Delete", deletes the popup and removes its row without reloading the list. The server marks it deleted. The row buttons are disabled while it runs. | [`POST ?action=admin_delete_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_delete_mkt_popup) |

## States

* **Loading:** the table shows its spinner while the list loads; the delete button spins while its delete runs.
* **Empty:** with no popups, the table has no rows.
* **Error:** a failed list load shows no message and leaves the table empty. A failed delete shows the server's message, and the row stays.
* **No permission:** none in the app.

## Dialogs and sheets

### Create or Edit Marketing Popup

Titled "Create Marketing Popup" or "Edit Marketing Popup"; a click outside does not close it. Its parts are headed "Campaign Collateral", "Campaign Duration" and "Week Days Duration", and the footer holds "Active", "Cancel" and "Save". It loads the time zones, the countries and the sites for its lists ([`GET ?action=read_parent_timezones`](https://docs.snapfix.com/engineering-reference/api/reference.md), [`GET ?action=countries_list`](https://docs.snapfix.com/engineering-reference/api/reference.md), [`GET /v4/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v4parents)).

| Field                       | Type                                                              | Required                    | Default                                                      | Rules and messages                                                                                                                                                                                                                                                                                                                                               |
| --------------------------- | ----------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                        | Text, up to 20 characters, with a counter such as "8/20"          | Yes                         | Empty                                                        | "Please input Name field"                                                                                                                                                                                                                                                                                                                                        |
| Portrait image              | Image upload: "\* Upload portrait image", drag a file or pick one | Yes                         | Empty; the saved image when editing                          | Image files only: "Please upload correct image file!". Taller than wide: "Please upload correct portrait image". A file that cannot be read: "Unable to load image data". Once set, the image shows with "Preview" and "Remove".                                                                                                                                 |
| Landscape image             | Image upload: "\* Upload landscape image"                         | Yes                         | Empty; the saved image when editing                          | As the portrait image, but wider than tall: "Please upload correct landscape image".                                                                                                                                                                                                                                                                             |
| Url                         | Web address                                                       | No                          | Empty; the saved link when editing                           | "Please input valid Url" when it is not a web address. A valid address shows "Please click the arrow button to preview" until the arrow button beside it opens the address in a new tab; then "\* I confirm the URL is working" appears, and "Save" needs it ticked. A saved link counts as confirmed.                                                           |
| Account(s)                  | Multi-select with search                                          | No                          | None; the popup's sites when editing                         | Placeholder "All accounts selected": with no site picked, the popup is saved without a site list, and the apps show it to every site.                                                                                                                                                                                                                            |
| Duration                    | Date range                                                        | Yes                         | Empty                                                        | "Please select Start and End date". The campaign runs from 00:00 on the first day to 23:59 on the last day, in the time zone below.                                                                                                                                                                                                                              |
| Timezone                    | Select with search, "Select a Timezone"                           | No                          | `Europe/Dublin` for a new popup; the saved zone when editing | The field has no rule, so its message "Please select Timezone" never shows, and a cleared zone saves as GMT.                                                                                                                                                                                                                                                     |
| Language                    | Select with search, "Select a Language"                           | No                          | Empty                                                        | A list of ISO 639-1 languages built into the admin app, each as "Name (CODE)".                                                                                                                                                                                                                                                                                   |
| Country                     | Select with search, "Select a Country"                            | Yes, once a language is set | Empty; disabled until a language is set                      | "Please select Country". Sorted by name. Clearing the language clears the country. With both set, the locale shows beside the language, such as `en-IE`, and is saved that way.                                                                                                                                                                                  |
| IOS, Android, Web           | Checkboxes                                                        | No                          | All ticked                                                   | A platform left unticked does not get the popup.                                                                                                                                                                                                                                                                                                                 |
| Week days, "Mon:" to "Sun:" | A checkbox and a two-handle slider per day                        | At least one day            | Every day ticked, 00:00 to 24:00                             | The slider runs from "00:00" to "24:00" in steps of two hours. Unticking a day puts its slider back to the whole day and locks it. "Save" stays disabled until a ticked day has a window other than 00:00 to 00:00, with no message saying why. Each ticked day saves its start hour and length; an unticked day, or one set to 00:00 to 00:00, saves no window. |
| Active                      | Checkbox, in the footer                                           | No                          | Ticked                                                       | Unticked saves the popup as not active.                                                                                                                                                                                                                                                                                                                          |

"Save" is enabled while the form is valid, a week day has a window, an edited popup has finished loading, and a typed link is confirmed. It uploads each new image, one after the other, then creates or changes the popup ([`POST ?action=save_image`](https://docs.snapfix.com/engineering-reference/api/files.md), then [`POST ?action=admin_create_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_mkt_popup) or [`POST ?action=admin_modify_mkt_popup`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_modify_mkt_popup)). On success "Success" shows, the dialog closes and the list reloads; a failed save shows the server's message. While it saves, the form, "Cancel", the close button and a click outside do nothing. When an image cannot be uploaded, the dialog shows "Unable to save portrait image." or "Unable to save landscape image." and stays that way: the form stays disabled and "Save" keeps spinning.

When editing, a spinner covers the dialog until the popup loads; if it cannot be loaded, the server's message shows and the dialog closes. The dates are rebuilt by reading the stored times as text in the popup's locale, so a day-first locale such as `en-IE` swaps or loses them, and a save then stores the wrong dates, or none. A popup with no time zone is edited with the zone "GTM", which is not a zone name, so loading stops part way: the dates, language, link, platforms, days and sites stay unfilled.

### Delete confirmation

A popover on the delete button: "Are you sure you want to delete the item?" with "Delete".

### Image preview

A full-size viewer, opened from a table's preview button or from the dialog's "Preview".


---

# 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/how-the-apps-work/screens/staff/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.
