Read and change a marketing banner or popup

# Read and change a marketing banner or popup

Banner and popup each have a get/apply pair, with create, visibility and configure actions inside one writer.

## Read the chosen screen

Use [marketing_banner_get](../tools/publ_marketing_banner_get.md) or [marketing_popup_get](../tools/publ_marketing_popup_get.md). A banner read has this input:

```json
{
  "channelCode": "selected-channel-code"
}
```

Keep the returned revision, exists, customInitialized and editingAllowed. A missing/null widget is distinct from an uninitialized custom record. A malformed successful response is an error. The reader initializes nothing and fetches no stored image or link. Popup description is decoded for the editor; its revision still protects the exact stored representation.

## Choose the action

Use the matching [banner](../tools/publ_marketing_banner_apply.md) or [popup](../tools/publ_marketing_popup_apply.md) writer:

- create installs inactive source defaults only when the selected widget is absent. An existing widget remains unchanged.
- visibility changes only the existing widget's displayed state. It requires visible and preserves all content.
- configure combines supplied settings, image replacement/removal and optional visible in one nested save. It requires editor-plan eligibility, including when only visible is supplied.

This banner visibility plan is illustrative. Replace the placeholders with a fresh read from the intended authorized channel:

```json
{
  "channelCode": "selected-channel-code",
  "requestId": "banner-guide-visibility-001",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "action": "visibility",
  "visible": false,
  "dryRun": true
}
```

A new dry run performs reads and checks without writing a journal or business data. Inspect noop and plannedStages. For an authorized change, use the intended input with dryRun:false, the default when omitted. A stale revision requires a new read and reassessment, not rewriting an old task.

## Plan and input rules

Creation and visibility have no editor-plan gate. Configure rejects FREE_TRIAL, NORMAL_BASIC, NORMAL_STARTER_2023_04 and NORMAL_STARTER. Eligible source plans are NORMAL_ESSENTIAL, NORMAL_BUSINESS, NORMAL_PRO, NORMAL_FROM_ENTERPRISE, ENTERPRISE_TRIAL, ENTERPRISE_ENTERPRISE, PARTNER_TRIAL, PARTNER_PARTNER and INTERNAL_INTERNAL. Missing/unrecognized plans have editingAllowed:null and block configure. The returned human-console guidance does not perform an upgrade, charge or billing change.

Omitted fields preserve existing values. Text accepts empty or at least two characters, with the per-screen limits in the writer. Links remove whitespace and add https:// when omitted, then validate HTTP(S), no embedded credentials and the source pattern. Popup button visibility preserves hidden button fields; configured visible buttons require valid-length text and a nonempty destination. Pass editor newlines when changing popup description; omit it to preserve exact storage bytes.

Images use original PNG/JPEG filename/base64 objects, null to remove, or omission to preserve. All replacement images together are limited to 5 MiB by bridge policy; the source widget has no equivalent explicit limit. The bridge does not fetch supplied URLs or resize files.

## Interpret completion and continuation

The workflow may initialize custom settings, upload images and save one full nested widget. It rereads the complete custom business state, preserving the other widget and unrelated settings. No recache request is made. Separate acknowledgements and upload receipts describe observed stages; there is no transaction, automatic rollback or orphan deletion.

Retain taskType marketing-widget and the original taskId/input. Status describes history; resume may continue untouched work. Initialization/save attempts can only be reconciled by readback and are never resent. Attempted grants/uploads hold for inspection. Unstarted replacement images after restart need the original apply and identical bytes.

The exact returned console URL identifies the selected screen; it does not authenticate the browser. Scope, plan variants, initial creation, interrupted recovery, UI/LLM and hosted behavior require their own evidence.