# Seguimiento de suscripciones de la App Store

<Aside type="caution" icon="setting" title="Se necesita asistencia de un desarrollador">
Necesitará la ayuda de su equipo de desarrollo para configurar esta integración. Por favor, comparta esta guía con ellos.
</Aside>

## Resumen de la integración

[App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications) es el servicio de servidor a servidor de Apple que envía a su backend un mensaje en tiempo real cada vez que cambia el estado de una suscripción.

Al conectar las Notificaciones del Servidor de la App Store a Pushwoosh, puede reaccionar a todo el ciclo de vida de la suscripción, incluyendo compras, renovaciones, cancelaciones, problemas de facturación, expiraciones y reembolsos, sin necesidad de construir su propia infraestructura de backend. Cada vez que el estado de una suscripción cambia en la cuenta de la App Store de un usuario, Apple notifica a Pushwoosh, y Pushwoosh dispara el evento [`PW_Subscription*`](#tracked-events) correspondiente en el perfil del usuario.

<Aside type="note">
Esta integración es compatible con **suscripciones de iOS** (Notificaciones del Servidor de la App Store V2). Para realizar un seguimiento de las suscripciones de Android, consulte [Seguimiento de suscripciones de Google Play](/es/product/integrations/google-play-subscription-tracking/).
</Aside>

### Tipo de integración

**Fuente:** Las Notificaciones del Servidor de la App Store se envían desde Apple a Pushwoosh.

### Eventos rastreados

Pushwoosh asigna cada notificación compatible de la App Store a un conjunto de eventos unificado `PW_Subscription*`, para que pueda activar campañas en cualquier etapa del ciclo de vida de la suscripción.

| Evento | Se dispara cuando |
| ----- | ---------- |
| `PW_SubscriptionStart` | Un usuario compra la suscripción por primera vez. |
| `PW_SubscriptionRenew` | La suscripción se renueva automáticamente para un nuevo período de facturación. |
| `PW_SubscriptionCancel` | Un usuario desactiva la renovación automática. La suscripción permanece activa hasta que expira. |
| `PW_SubscriptionResume` | Un usuario vuelve a habilitar la renovación automática o se vuelve a suscribir antes de que la suscripción caduque. |
| `PW_SubscriptionBillingIssue` | Falla un pago de renovación y la suscripción entra en el período de reintento de facturación de Apple. |
| `PW_SubscriptionRecovered` | Una renovación que había fallado anteriormente se procesa y la suscripción vuelve a estar activa. |
| `PW_SubscriptionExpired` | La suscripción ha caducado por completo y ya no está activa. |
| `PW_SubscriptionRefund` | Apple reembolsa la compra o revoca el acceso. |

Cada evento lleva los mismos atributos:

- **productID:** el identificador de producto de la App Store de la suscripción.
- **expiresAt:** cuándo finaliza el período de pago actual, como una marca de tiempo Unix en segundos. Se incluye cuando Apple lo proporciona.

<details>

<summary>Cómo se asignan los eventos a las Notificaciones del Servidor de la App Store</summary>

Para los desarrolladores que verifican la integración, cada evento de Pushwoosh corresponde a estos valores de `notificationType` (y `subtype`) de la App Store:

| Evento de Pushwoosh | `notificationType` / `subtype` |
| --------------- | ------------------------------ |
| `PW_SubscriptionStart` | `SUBSCRIBED` / `INITIAL_BUY` |
| `PW_SubscriptionRenew` | `DID_RENEW` |
| `PW_SubscriptionCancel` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_DISABLED` |
| `PW_SubscriptionResume` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_ENABLED`, `SUBSCRIBED` / `RESUBSCRIBE` |
| `PW_SubscriptionBillingIssue` | `DID_FAIL_TO_RENEW` |
| `PW_SubscriptionRecovered` | `DID_RENEW` / `BILLING_RECOVERY` |
| `PW_SubscriptionExpired` | `EXPIRED` |
| `PW_SubscriptionRefund` | `REFUND`, `REVOKE` |

Otros tipos de notificaciones, como aumentos de precios, cambios de plan, en espera y solicitudes de consumo, se reconocen pero no publican un evento.

</details>


### Cómo funciona

1. El estado de una suscripción cambia en la cuenta de la App Store de un usuario (una compra, renovación, cancelación, etc.).
2. Apple envía una Notificación del Servidor de la App Store (V2) a su URL de notificación de Pushwoosh.
3. Pushwoosh decodifica la carga útil firmada y lee el `appAccountToken` de la transacción.
4. Pushwoosh busca el dispositivo cuyo HWID coincide con ese token, encuentra al usuario vinculado a él y publica el evento `PW_Subscription*` correspondiente para ese usuario.

<Aside type="caution" title="Importante">
La coincidencia entre una transacción de la App Store y un usuario de Pushwoosh se basa en el `appAccountToken`. Si su aplicación no establece este token en el momento de la compra, Pushwoosh recibe la notificación pero **no se publica ningún evento**. Consulte [cómo establecer `appAccountToken`](#set-appaccounttoken-to-the-devices-pushwoosh-hwid).
</Aside>

### Casos de uso

**Recuperar suscriptores que abandonan:** Desactivar la renovación automática no finaliza el acceso de inmediato. La suscripción permanece activa hasta que finaliza el período de pago, y esa es su ventana para recuperar al usuario. En `PW_SubscriptionCancel`, lance un [Customer Journey](/es/product/customer-journey/pushwoosh-journey-overview/) con un push de retención, un [correo electrónico](/es/product/messaging-channels/emails/) sobre las características que perderían, o un [mensaje in-app](/es/product/messaging-channels/in-apps/) con un descuento de renovación antes de que el acceso caduque.

**Incorporar nuevos suscriptores:** Active una serie de bienvenida en `PW_SubscriptionStart` para ayudar a los usuarios a obtener valor de su plan desde el principio y preparar el terreno para la renovación.

**Rescatar pagos fallidos:** Cuando se dispara `PW_SubscriptionBillingIssue`, un pago de renovación no se ha procesado y la suscripción está en la ventana de reintento de Apple. Pida al usuario que actualice su método de pago antes de que pierda el acceso, y haga un seguimiento con `PW_SubscriptionRecovered` para confirmar una vez que se haya resuelto.

**Volver a atraer a usuarios inactivos:** Inicie una campaña de reactivación en `PW_SubscriptionExpired` con una oferta de cliente recurrente para los suscriptores que han abandonado por completo.


## Configuración de la integración

### Establecer `appAccountToken` en el HWID de Pushwoosh del dispositivo

Pushwoosh identifica al usuario correcto a partir del **HWID** del dispositivo, por lo que su aplicación debe adjuntar el HWID de Pushwoosh del dispositivo como el `appAccountToken` cuando se compra la suscripción a través de StoreKit.

Por defecto, el SDK de iOS de Pushwoosh utiliza el `identifierForVendor` (IDFV) del dispositivo como HWID. IDFV ya es un `UUID`, exactamente el formato que Apple requiere para `appAccountToken`. Pushwoosh luego resuelve automáticamente al usuario actualmente vinculado a ese dispositivo, por lo que esto funciona tanto si asigna sus propios ID de usuario con `setUserId` como si no.

<Tabs>
<TabItem label="StoreKit 2">
```swift
// Adjuntar el HWID de Pushwoosh del dispositivo (el IDFV por defecto) como el appAccountToken
var options: Set<Product.PurchaseOption> = []
if let hwid = UIDevice.current.identifierForVendor {
    options.insert(.appAccountToken(hwid))
}

let result = try await product.purchase(options: options)
```
</TabItem>
<TabItem label="StoreKit 1">
```swift
// applicationUsername debe ser una cadena UUID para poblar appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)
```
</TabItem>
</Tabs>

<Aside type="caution">
Si su aplicación anula el HWID de Pushwoosh (por ejemplo, a través del módulo de HWID persistente [`PushwooshKeychain`](/es/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) o un valor personalizado), establezca `appAccountToken` en ese mismo HWID. El token debe coincidir con el HWID del dispositivo en Pushwoosh, o el evento no se podrá atribuir.
</Aside>

### Encontrar su Código de Aplicación de Pushwoosh

Abra su aplicación en el Panel de Control de Pushwoosh. Su **Código de Aplicación** (formato `XXXXX-XXXXX`) se muestra debajo del nombre del proyecto en la barra lateral.

Necesitará el Código de Aplicación para construir la URL de notificación.

### Añadir la URL de notificación en App Store Connect

1. En [App Store Connect](https://appstoreconnect.apple.com/), vaya a **Apps → su app → Información de la app** (en *General*), y desplácese hasta **Notificaciones del Servidor de la App Store**.
2. Seleccione notificaciones de la **Versión 2**.
3. Establezca tanto la **URL del Servidor de Producción** como la **URL del Servidor de Sandbox** en:

```
https://appstore-notifications.pushwoosh.com/appstore/YOUR_APPLICATION_CODE/
```

4. Reemplace `YOUR_APPLICATION_CODE` con el Código de Aplicación del paso anterior. Mantenga la barra inclinada final.

<Aside type="note">
Si su cuenta está alojada en el **centro de datos de EE. UU.**, use `https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/` en su lugar. Si no está seguro de qué centro de datos utiliza su cuenta, póngase en contacto con su Gerente de Éxito del Cliente o con el [Soporte de Pushwoosh](https://www.pushwoosh.com/contact-us/).
</Aside>

### Confirmar los eventos en Pushwoosh

Pushwoosh registra cada evento `PW_Subscription*` en su proyecto la primera vez que ocurre, con los atributos `productID` y `expiresAt`. Después de una prueba en el sandbox, abra **Audiencia → Eventos** para verificar que los eventos aparecen. Luego están listos para la segmentación, las estadísticas y los Customer Journeys.

### Construir su campaña

Cree un [Customer Journey](/es/product/customer-journey/pushwoosh-journey-overview/) con una [entrada basada en un disparador](/es/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/) en cualquier evento `PW_Subscription*`, por ejemplo `PW_SubscriptionCancel` para recuperación o `PW_SubscriptionStart` para incorporación, y añada los mensajes que desea enviar.

## Pruebas

Las Notificaciones del Servidor de la App Store se pueden activar en el entorno **Sandbox** de Apple. Para verificar la integración:

1. Realice una compra de suscripción en el sandbox con `appAccountToken` establecido como se describió anteriormente. Esto dispara `PW_SubscriptionStart`.
2. Desactive la renovación automática desde la pantalla de gestión de suscripciones del dispositivo. Esto dispara `PW_SubscriptionCancel`.
3. En el Panel de Control de Pushwoosh, abra el perfil del usuario y vaya al [Historial de eventos](/es/product/audience-data-and-segmentation/user-explorer/#events-history-tab).
4. Confirme que los eventos aparecen en unos instantes.