> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Push

> Design iOS Push notification templates with title, body, image, and action URL — with a live lock screen preview.

The iOS Push editor is a form with title, body, image, and action URL — with a live lock screen preview on the right. Content is personalised with [Handlebars](/docs/handlebars-helpers) variables (`{{variable_name}}`).

<Frame caption="iOS Push editor with live lock screen preview">
  <img src="https://mintcdn.com/suprsend/sGhtraHJZNmyh1Op/images/docs/templates-editor-ios-push.png?fit=max&auto=format&n=sGhtraHJZNmyh1Op&q=85&s=a2830bb7278f6f95fbd5e4a4813f2bc4" width="1024" height="645" data-path="images/docs/templates-editor-ios-push.png" />
</Frame>

## iOS Push fields

**Title** — single-line heading. Keep under 30 characters — iOS truncates on the lock screen. Supports Handlebars variables.

**Body** — multi-line message text. Front-load key info in the first line (4 lines visible in expanded view). Supports Handlebars variables.

**Image URL** — *optional.* Public URL for a rich notification image (PNG, JPG, JPEG, min 1024x1024 for best rendering). GIFs play in the expanded view. Requires a Notification Service Extension in your app — the SuprSend iOS SDK includes this by default. See [iOS SDK integration](/docs/ios-integration).

**Action URL** — *optional.* URL opened on tap. Always set one — without it, tapping opens the app's default screen. Supports deep links and Handlebars variables.

## Adding dynamic content

You can add variables in the template to personalise it for each recipient. Variables are replaced with actual data at send time.

<Steps>
  <Step title="Add variables in the Variables panel">
    Add sample data in the **Variables panel** (Input Payload section) on the left side of the editor. This powers auto-suggestions and the live preview. For the full guide, see [Adding dynamic content](/docs/templates#the-variables-panel).
  </Step>

  <Step title="Use variables in the template">
    Type `{{` in any field — matching variables appear as auto-suggestions. You can also type variable names manually following [Handlebars syntax](https://handlebarsjs.com/guide/#what-is-handlebars).

    **Examples using this sample data:**

    <CodeGroup>
      ```json json theme={"system"}
      {
        "event": {
          "location": {
            "city": "San Francisco",
            "state": "California"
          },
          "order_id": "11200123",
          "first_name": "Joe"
        },
        "product_image_url": "https://yourapp.com/images/product.jpg"
      }
      ```
    </CodeGroup>

    * **Nested variable:** `{{event.location.city}}` → renders as `San Francisco`
    * **Variable with space in name:** `{{event.[first name]}}`

    The preview section shows sample values rendered in real-time. If a variable isn't rendering, check:

    1. The variable is defined in the Variables panel.
    2. The variable name matches the Handlebars syntax exactly.
  </Step>
</Steps>

<Warning>
  If a variable cannot be rendered at send time (missing or mismatched data), SuprSend discards the iOS Push notification for that user. Other channels in the same template group are still sent.
</Warning>

## Preview and test

The right panel shows a live iOS lock screen preview, updated in real time as you edit. Variables render using data from the **Variables panel**.

Click **Test** in the top-right corner to send a real push notification to a real device. This uses the **live version** — commit your changes before testing. See [Testing a Template](/docs/templates#test) for the full guide.

## Commit

Click **Commit** in the top bar to publish the current draft as a new live version. Add an optional description for versioning.

## Common scenarios

<AccordionGroup>
  <Accordion title="Delivery update">
    | Field      | Value                                                       |
    | ---------- | ----------------------------------------------------------- |
    | Title      | `Your order is out for delivery`                            |
    | Body       | `Order #{{order_id}} will arrive by {{eta}}. Tap to track.` |
    | Image URL  | `{{product_image_url}}`                                     |
    | Action URL | `https://yourapp.com/track/{{order_id}}`                    |
  </Accordion>

  <Accordion title="Social engagement">
    | Field      | Value                            |
    | ---------- | -------------------------------- |
    | Title      | `{{actor_name}} liked your post` |
    | Body       | `"{{post_excerpt}}"`             |
    | Action URL | `yourapp://posts/{{post_id}}`    |
  </Accordion>

  <Accordion title="Restock reminder">
    | Field      | Value                                           |
    | ---------- | ----------------------------------------------- |
    | Title      | `Running low?`                                  |
    | Body       | `It might be time to restock {{product_name}}.` |
    | Image URL  | `{{product_image_url}}`                         |
    | Action URL | `https://yourapp.com/product/{{product_id}}`    |
  </Accordion>
</AccordionGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Why aren't images showing in my push notification?">
    Your app needs a **Notification Service Extension** to display rich media (images, GIFs). The SuprSend iOS SDK includes this by default. If you're not using the SDK, add the extension manually. Supported formats: JPEG, PNG, GIF. Max size: 10 MB. Images display in the expanded notification view (long-press or swipe down). See [iOS SDK integration](/docs/ios-integration).
  </Accordion>

  <Accordion title="How do deep links work in iOS push?">
    The **Action URL** supports three URL types:

    | URL type       | Format                                                | Behaviour                                                                                                           |
    | -------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
    | Web URL        | `https://yourapp.com/orders/123`                      | Opens in Safari (or your app if [Universal Links](https://developer.apple.com/ios/universal-links/) are configured) |
    | Custom scheme  | `yourapp://orders/123`                                | Opens the matching view controller in your app                                                                      |
    | Universal Link | `https://yourapp.com/orders/123` (Associated Domains) | Opens your app directly                                                                                             |

    Prefer Universal Links — they work as both web fallback and in-app deep links.
  </Accordion>

  <Accordion title="How does badge count work?">
    SuprSend increments the app badge by 1 for each notification. Clear the badge in your app when the user opens it or reads notifications.
  </Accordion>

  <Accordion title="What happens if a variable is missing at send time?">
    SuprSend discards the iOS Push notification for that user. Other channels in the same template group are still sent if they render successfully.
  </Accordion>
</AccordionGroup>