Salla App UI Builder

Salla App Store Listing Page (app_page_builder)

The listing page is the app's home/landing page shown to merchants on the App Store and when they install it. It is an ordered list of blocks (App Information, Features, Reviews, Brands, FAQ, Stats — revealed dynamically by init / catalog), authored entirely through the app_page_builder MCP tool — there is no REST endpoint or token to handle. Drive listing-page work through app_page_builder and salla_upload.

Editing a block's element values writes the shared listing content directly into the app's draft publication. The fields this tool owns: name, description, logo, screenshots, benefits (value shapes in blocks-and-fields.md).

short_description belongs elsewhere — it lives in the publication's basic_information section (50–200 chars) and is written via app_publish → salla-publication-consistency. Author it there, not here.

Prerequisite: open a draft first

app_page_builder is enabled once the app is public and has a draft publication. Create the draft first:

app_publish action=open

The publish/draft lifecycle (open, fill the publication sections, validate + save the draft, then the partner submits in the Portal) is owned by salla-publication-consistency — read that skill for the full flow. app_page_builder writes the shared listing content into the draft once it exists.

The 9 actions

All calls take action= (and the app context the MCP already holds). Discover shapes with the read actions (catalog, list, show) before writing.

Typical flow: app_publish action=open → app_page_builder action=init (seed required blocks) → action=list → action=show (per block, to learn its element keys) → action=set (write values) → action=add/remove/sort as needed.

The full action contract (parameters, returns, errors) is in api-spec.md.

Media (logo, screenshots)

Image elements (logo, screenshots) reference an uploaded media id:

1. salla_upload with a source_url → returns an integer image id.
2. Put [{ id, url }] in that element's set value.

Keep an existing image by leaving its stored { id, url } in place when you set.

Generating missing listing images (canonical recipe)

This is the shared recipe every listing/publication image field points to. It covers all the App-Store image fields across the builder, the publication, and the embedded app:

Dimensions and counts above (logo 1:1 ≥250×250, ≥3 screenshots, exactly 3 benefits) are enforced server-side on save — action=set returns error.fields if they're off. Confirm the live requirement for a builder field via app_page_builder action=show rather than treating these numbers as builder-FE guarantees.

banner and embedded_image are publication fields, not builder fields — set them via app_publish (salla-publication-consistency); embedded_image is the Embedded App Banner and applies only when the app has an iframe page (salla-embedded-app, which also owns the second Salla-promotional image). logo is also set at app creation (salla-app-builder Step 1).

When any of these is missing — or you're assembling the first publication — and an image-generation tool is available to you, generate an image that fits the app's purpose and brand, then upload and set it:

1. Confirm the required dimensions/aspect first for that field from the table above (and action=catalog / action=show / blocks-and-fields.md for builder fields) — so the upload isn't rejected.
2. Generate the image at that size to match the app.
3. Upload it with salla_upload → returns the image id.
4. Set it via the field's tool: builder fields (logo, screenshots, benefit images) via app_page_builder; banner / embedded_image via app_publish features section.

Listing images must be real — ask first, placeholder only with a heads-up

A complete listing needs real images: logo + ≥3 screenshots (App Information), banner + embedded_image (App Features, per the table above). The discipline when any are missing:

1. Ask the user to provide all the required images. Don't invent a real-looking image and don't silently skip a field — this is verify-don't-invent. (If an image-generation tool is available and the user wants generated art, use the generate-then-upload recipe above.)
2. If the user skips or declines, proceed with clearly-marked default placeholders so the draft still validates — then explicitly tell the partner to replace the placeholders in the Portal before the one-click submit (the submit step → salla-publication-consistency). Never present a placeholder image as final.

Gate: "Every listing image is a real partner asset — or a placeholder the partner has been explicitly told to replace before submitting?"

Auto-fill: the default template

A published app already has a listing page: the default template renders from publication data. app_page_builder writes into that same draft, so partial customization mixes with the default template.

The model

• An app's listing = the ordered array of blocks returned by action=list.
• The catalog (action=catalog) is the full set of block types you can add.
• A block carries id, slug, order, and the flags is_required, editable, is_visible; its editable inputs are elements (key → value), discovered via action=show.
• app-information is the one pinned block — init seeds it and remove rejects it. The remaining required/optional blocks are revealed dynamically by init / catalog; confirm the live set at call time.

See Blocks and Fields for the block/element model and how to discover types and element keys, API spec for the action contract, and Payloads for set value shapes. Example block ids and element keys are illustrative — confirm them with action=catalog / action=show.

Things to keep in mind

• Run init first on a fresh draft — it seeds the required blocks and returns the current page.
• Confirm ids and keys at call time with action=catalog (block types) and action=show (element keys); example ids/keys in this skill are illustrative.
• App Information is the one pinned block — always present, stays first, can't be removed. The rest of the required/optional blocks are revealed by init / catalog (slugs illustrative — confirm at call time). App Plans always renders on the listing as a placeholder (even when the app has no plans) — but it's not an editable builder block; populate it via the publish flow's pricing step → salla-publication-consistency / salla-app-billing.
• Contact details live in the publication's contact_information section → salla-publication-consistency. Some support/contact channels may also surface on App Information as flat support_* elements — confirm with action=show.
• Lingual elements carry both Arabic and English ({ "ar": "…", "en": "…" }).
• Collection element children are keyed with the collection id as a prefix (features.title). See payloads.md.
• image and richtext values render as public App-Store content — use only trusted, sanitized assets/HTML.

Red Flags

Cross-links

• salla-publication-consistency — the draft/publish lifecycle (app_publish action=open, the publication sections, short_description, contact_information).
• salla-app-builder — create/configure/publish an app end to end.
• salla-app-settings — merchant settings.
• salla-docs — schemas and doc lookup.

Resources