# iOS Push-Primer

Ein Push-Primer ist ein Soft-Opt-in-Dialog, den Sie **vor** der iOS-Systemabfrage für Push-Berechtigungen anzeigen. iOS zeigt die Systemabfrage nur einmal pro Installation an – wenn der Benutzer auf **Nicht erlauben** tippt, gehen die Push-Benachrichtigungen verloren, bis er sie in den Einstellungen wieder aktiviert. Der Primer ermöglicht es Ihnen, zuerst den Nutzen zu erklären und im richtigen Moment zu fragen, sodass Sie die einmalige Systemabfrage für Benutzer verwenden, die bereits zugestimmt haben.

Verfügbar seit Version 7.1.1. Der Primer ist Teil des `PushwooshFramework`; es ist kein zusätzliches Modul erforderlich.

<figure style={{ textAlign: "center" }}>
  <img
    src="/ios-push-primer-1.webp"
    alt="Push-Primer-Dialog, der vor der System-Berechtigungsabfrage angezeigt wird"
    style={{ display: "block", margin: "0 auto", maxWidth: "300px", height: "auto" }}
    width="300"
  />
  <figcaption>Push-Primer, der vor der iOS-System-Berechtigungsabfrage angezeigt wird</figcaption>
</figure>

## Wie es funktioniert

Der Primer ist vollständig zustandsbewusst. Er liest den aktuellen Autorisierungsstatus für Benachrichtigungen und entscheidet, was zu tun ist, sodass er bei jedem Start sicher aufgerufen werden kann:

- **Nicht festgelegt** – zeigt den Primer an; bei Zustimmung wird die System-Berechtigungsabfrage ausgelöst.
- **Autorisiert oder vorläufig** – unterdrückt den Primer stillschweigend (es wird nichts angezeigt).
- **Abgelehnt** – zeigt den Primer an; bei Zustimmung leitet er den Benutzer zu den Benachrichtigungseinstellungen der App weiter (wenn `fallbackToSettings` aktiviert ist).

Sie entscheiden, **wann** Sie den Primer aufrufen (zum Beispiel nach dem Onboarding oder nach einer wichtigen Aktion). Das SDK erzwingt kein eigenes Timing, mit Ausnahme der optionalen `minInterval`-Drosselung, die unten beschrieben wird.

## Grundlegende Verwendung

Konfigurieren Sie den Primer mit einem Fluent Builder und rufen Sie `present` auf. Die Mindestkonfiguration erfordert einen Titel, eine Nachricht und die Titel der beiden Schaltflächen.

<Tabs>
<TabItem label="Swift">
```swift
import PushwooshFramework

Pushwoosh.configure.pushPrimer
    .title("Stay in the loop")
    .message("Get notified about deals and order updates first")
    .acceptButton("Enable notifications")
    .declineButton("Not now")
    .present()
```
</TabItem>
</Tabs>

<Aside type="note">
Rufen Sie den Primer auf, nachdem die Benutzeroberfläche der App auf dem Bildschirm angezeigt wird (zum Beispiel kurz nach dem Start oder an einem bestimmten Schritt in Ihrem Ablauf), damit er über Ihrer Benutzeroberfläche präsentiert werden kann.
</Aside>

## Stile und Positionen

Verwenden Sie `style`, um zwischen einer Systemwarnung und einem benutzerdefinierten Sheet zu wählen, und `position`, um das benutzerdefinierte Sheet zu platzieren. Jede Position hat ihr eigenes Standarddesign.

| Wert | Beschreibung |
|-------|-------------|
| `.alert` | System-`UIAlertController`. Die Position wird ignoriert. |
| `.sheet` + `.bottom` | Unteres Sheet, das nach oben gleitet, mit einem Greifer und Schaltflächen über die gesamte Breite (Standard). |
| `.sheet` + `.top` | Kompaktes Banner, das von oben hereinfällt, wie eine Benachrichtigung. |
| `.sheet` + `.center` | Zentrierter Dialog, der skaliert und eingeblendet wird. |

<Tabs>
<TabItem label="Swift">
```swift
Pushwoosh.configure.pushPrimer
    .style(.sheet)
    .position(.top)
    .title("Stay in the loop")
    .message("Get notified about deals and order updates first")
    .acceptButton("Enable notifications")
    .declineButton("Not now")
    .present()
```
</TabItem>
</Tabs>

<img src="/ios-push-primer-positions.webp" alt="Push-Primer in unterer, oberer und mittlerer Position"/>

## Anpassung

Alle visuellen Einstellungen sind optional – lassen Sie sie weg, um die nativen Standardeinstellungen zu verwenden, die sich an den Hell- und Dunkelmodus anpassen.

<Tabs>
<TabItem label="Swift">
```swift
Pushwoosh.configure.pushPrimer
    .style(.sheet)
    .position(.center)
    .title("Stay in the loop")
    .message("Get notified about deals and order updates first")
    .acceptButton("Enable notifications")
    .declineButton("Not now")
    .image(UIImage(named: "PrimerHero"))          // lokales Bild oder .imageURL("https://…")
    .backgroundColor(.systemBackground)
    .titleColor(.label)
    .messageColor(.secondaryLabel)
    .acceptButtonColor(.systemBlue)
    .acceptButtonTextColor(.white)
    .declineButtonColor(.clear)
    .declineButtonTextColor(.secondaryLabel)
    .cornerRadius(24)
    .buttonCornerRadius(14)
    .buttonBorderColor(.separator)
    .present()
```
</TabItem>
</Tabs>

Anpassungsreferenz:

| Setter | Beschreibung |
|--------|-------------|
| `image` / `imageURL` | Ein lokales `UIImage` oder eine Remote-URL. Wird als Kreis im mittleren und unteren Layout und als Symbol im oberen Banner gerendert. Ein lokales Bild hat Vorrang vor einer URL. |
| `backgroundColor` | Einfarbige Hintergrundfarbe der Karte. |
| `backgroundGradient` | Ein Array von Farben, das als weicher, mehrfarbiger Verlauf gerendert wird. Überschreibt `backgroundColor`. |
| `titleColor` / `messageColor` | Textfarben für Titel und Nachricht. |
| `acceptButtonColor` / `acceptButtonTextColor` | Hintergrund- und Textfarben der „Akzeptieren“-Schaltfläche. Die Akzeptieren-Farbe färbt auch das Standardsymbol ein. |
| `declineButtonColor` / `declineButtonTextColor` | Hintergrund- und Textfarben der „Ablehnen“-Schaltfläche. |
| `cornerRadius` | Eckenradius der Karte. |
| `buttonCornerRadius` / `buttonBorderColor` | Eckenradius und Randfarbe beider Schaltflächen. |

<Aside type="note">
Der Primer zeigt genau die Zeichenfolgen an, die Sie übergeben. Für mehrere Sprachen übergeben Sie lokalisierte Zeichenfolgen (zum Beispiel mit `NSLocalizedString`).
</Aside>

## Verhaltenseinstellungen

### Fallback zu den Einstellungen

Wenn Benachrichtigungen bereits abgelehnt wurden, wird der Primer standardmäßig angezeigt und die „Akzeptieren“-Schaltfläche führt den Benutzer zu den Benachrichtigungseinstellungen der App. Übergeben Sie `false`, um den Primer im abgelehnten Zustand stattdessen vollständig zu unterdrücken.

```swift
.fallbackToSettings(false)
```

### Anzeigehäufigkeit

Standardmäßig hat der Primer keine eingebaute Drosselung – er wird angezeigt, wann immer Sie `present` aufrufen (und wird automatisch unterdrückt, sobald Benachrichtigungen autorisiert sind). Verwenden Sie `minInterval`, um zu begrenzen, wie oft der Primer erneut erscheint. Die Zeit der letzten Anzeige wird über Starts hinweg gespeichert.

```swift
.minInterval(7 * 24 * 60 * 60)   // höchstens einmal pro Woche anzeigen
```

## Ergebnis verarbeiten

Übergeben Sie eine Completion an `present`, um auf das Ergebnis zu reagieren.

<Tabs>
<TabItem label="Swift">
```swift
Pushwoosh.configure.pushPrimer
    .title("Stay in the loop")
    .message("Get notified about deals and order updates first")
    .acceptButton("Enable notifications")
    .declineButton("Not now")
    .present { outcome in
        switch outcome {
        case .accepted:            break   // angezeigt, Benutzer hat zugestimmt, Systemabfrage angefordert
        case .declined:            break   // angezeigt, Benutzer hat abgelehnt
        case .suppressed:          break   // nicht angezeigt (bereits autorisiert oder gedrosselt)
        case .redirectedToSettings: break  // abgelehnter Zustand, Benutzer zu den Einstellungen weitergeleitet
        @unknown default:          break
        }
    }
```
</TabItem>
</Tabs>

Das endgültige Ergebnis der Systemabfrage (der gewährte/abgelehnte Zustand und das Geräte-Token) kommt über die regulären Registrierungs-Callbacks an – der Primer verwendet `registerForPushNotifications` bei Zustimmung wieder und dupliziert diese Kette nicht.

## Referenzen

<CardGrid>
  <LinkCard
    title="iOS SDK API-Referenz"
    description="Vollständige technische Dokumentation, die alle öffentlichen Klassen, Methoden und Eigenschaften abdeckt."
    href="https://pushwoosh.github.io/pushwoosh-ios-sdk/"
  />
  <LinkCard
    title="Anpassen des iOS SDK"
    description="Andere Möglichkeiten, das Pushwoosh iOS SDK an Ihre App anzupassen."
    href="/developer/pushwoosh-sdk/ios-sdk/customizing-ios-sdk/"
  />
</CardGrid>