Saltar al contenido principal

Obtener tus credenciales de APNs (iOS)

Joryio envía notificaciones push a dispositivos iOS a través de Apple Push Notification service (APNs). Para ello necesita credenciales de tu cuenta de Apple Developer. Esta página explica paso a paso cómo crearlas en el portal de Apple e introducirlas en Joryio.

Cada app de Joryio tiene sus propias credenciales push, así que este proceso se hace una vez por cada app iOS. Un proyecto de React Native o Unity tiene una app iOS independiente en Joryio, y sus credenciales de APNs van ahí. Consulta Seguimiento multiplataforma.

Qué pide Joryio​

Joryio usa autenticación basada en token con una clave de autenticación de APNs (un archivo .p8). Necesitas cuatro cosas:

Campo en JoryioQué esDe dónde sale
EnvironmentDesarrollo (Sandbox) o Producción: el entorno de APNs en el que se registran las compilaciones de tu appEl tipo de compilación; consulta Elegir el entorno
Key IDIdentificador de 10 caracteres de la clave de autenticaciónCuenta de Apple Developer, Keys
Team IDIdentificador de 10 caracteres de tu equipo de desarrollo en AppleCuenta de Apple Developer, Membership details
Auth Key (.p8 Content)El texto completo del archivo .p8El archivo que descargas una sola vez al crear la clave

La configuración push también ofrece el método Basada en certificado (.p12). Esta guía cubre solo la clave .p8 basada en token, que es el método recomendado: una clave de autenticación no caduca y una sola clave puede enviar para todas las apps de tu equipo de desarrollo en Apple.

Antes de empezar​

  • Membresía en el Apple Developer Program. Las claves de APNs se crean en una cuenta de desarrollador de pago.
  • El rol Account Holder o Admin en ese equipo de desarrollo. Apple solo permite crear claves a estos roles. Si tienes otro rol, pide al Account Holder o a un Admin que cree la clave y te envíe el Key ID, el Team ID y el archivo .p8 por un canal seguro.
  • Notificaciones push activadas para tu app. En Xcode, añade la capacidad Push Notifications al target de tu app y asegúrate de que las notificaciones push estén activadas para el App ID (el bundle ID) en tu cuenta de desarrollador. La clave debe pertenecer al mismo equipo de desarrollo que la app.
  • Una app iOS en Joryio con el SDK de iOS integrado. Para crear una, consulta Creación de apps.

Paso 1: Crear la clave de autenticación de APNs​

  1. Inicia sesión en tu cuenta de Apple Developer y abre Certificates, Identifiers & Profiles.
  2. Haz clic en Keys en la barra lateral y luego en el botón de añadir (+).
  3. En Key Name, introduce un nombre que reconozcas más adelante, por ejemplo «Joryio push».
  4. Marca la casilla junto a Apple Push Notification service (APNs) y haz clic en Configure a su lado.
  5. Elige el entorno de la clave y el tipo de clave:
    • Entorno: elige el entorno que coincida con el que seleccionarás en Joryio (consulta Elegir el entorno). Una clave restringida a Sandbox no funciona para envíos de producción, y al revés.
    • Tipo de clave: Team Scoped funciona para todas las apps (bundle IDs) del equipo. Topic Specific se limita a los bundle IDs que selecciones; si la eliges, incluye el bundle ID de tu app.
  6. Haz clic en Continue, revisa la configuración de la clave y haz clic en Confirm.
  7. Haz clic en Download. La clave se guarda como un archivo de texto con extensión .p8.
  8. Haz clic en Done.
Solo puedes descargar la clave una vez

Apple no guarda una copia de la clave privada. Guarda el archivo .p8 en un lugar seguro, como el gestor de contraseñas de tu equipo. Si más adelante el botón Download está desactivado, la clave ya se descargó. Si pierdes el archivo, crea una clave nueva y revoca la anterior.

Paso 2: Anotar el Key ID y el Team ID​

  • Key ID: en Certificates, Identifiers & Profiles → Keys, haz clic en la clave que creaste. El Key ID aparece en los detalles de la clave, debajo de su nombre.
  • Team ID: en tu cuenta de Apple Developer, abre Membership details. El Team ID es una cadena de 10 caracteres.

Paso 3: Elegir el entorno​

APNs tiene dos entornos, y un token de dispositivo solo funciona en el entorno para el que se emitió:

  • Desarrollo (Sandbox): para compilaciones firmadas con un provisioning profile de desarrollo, por ejemplo cuando ejecutas la app desde Xcode en tu propio dispositivo.
  • Producción: para compilaciones firmadas con un provisioning profile de distribución: App Store y TestFlight.

Xcode establece el entorno push de la app a partir del provisioning profile, así que es la compilación la que decide en qué entorno se registran sus dispositivos. Cada app de Joryio tiene un único ajuste de entorno. Si pruebas con compilaciones de desarrollo y además publicas en la App Store, crea una app iOS aparte en Joryio para las compilaciones de desarrollo (con su propia clave de SDK), en lugar de cambiar el ajuste una y otra vez.

Paso 4: Introducir las credenciales en Joryio​

  1. En el panel de Joryio, ve a Configuración → Apps.
  2. Busca tu app iOS en la lista y haz clic en el icono Notificaciones push (campana) de su fila. Se abre la página Push notifications - [nombre de la app].
  3. En la tarjeta APNS credentials:
    • Environment: elige Desarrollo (Sandbox) o Producción.
    • Authentication Method: elige Basada en token (clave .p8).
    • Key ID: pega el Key ID del paso 2.
    • Team ID: pega el Team ID del paso 2.
    • Auth Key (.p8 Content): abre el archivo .p8 en un editor de texto y pega todo su contenido, incluidas las líneas -----BEGIN PRIVATE KEY----- y -----END PRIVATE KEY-----.
  4. Haz clic en Save configuration.

La lista de apps muestra ahora APNS configurado bajo el nombre de la app. La clave de autenticación se cifra en reposo y no vuelve a mostrarse: al reabrir la página, el campo está vacío con la nota «Configurado: déjalo vacío para conservar el valor actual o introduce uno nuevo para sustituirlo.». Déjalo vacío para conservar la clave guardada.

Paso 5: Enviar un push de prueba​

  1. Instala una compilación de tu app cuyo entorno coincida con el que elegiste, ábrela y permite las notificaciones. El SDK registra el token del dispositivo en Joryio.
  2. Crea una campaña push (o abre un borrador) que envíe desde esta app.
  3. Haz clic en Enviar Push de prueba en la variante, elige el usuario que tiene la sesión iniciada en tu dispositivo y envía.

Si la prueba falla, el mensaje de error incluye el motivo que devolvió APNs; búscalo en la tabla siguiente. Para el flujo completo de la campaña, consulta Notificaciones push.

Errores habituales y soluciones​

Lo que vesCausa probableSolución
BadDeviceTokenEl token del dispositivo se emitió para el otro entorno; por ejemplo, una compilación de TestFlight mientras Joryio está en Desarrollo (Sandbox).Ajusta Environment para que coincida con la compilación (consulta el paso 3) y vuelve a abrir la app en el dispositivo para que registre su token de nuevo.
DeviceTokenNotForTopicEl token pertenece a una app (bundle ID) distinta de aquella para la que envían las credenciales.Comprueba que el dispositivo ejecuta la app conectada a la clave de SDK de esta app de Joryio y que la clave pertenece al equipo de desarrollo propietario de la app.
InvalidProviderTokenEl Key ID, el Team ID o el contenido del .p8 no coinciden; por ejemplo, el Key ID de una clave con el contenido de otra, o una clave de otro equipo.Vuelve a introducir los tres valores de la misma clave y el mismo equipo. Pega el archivo .p8 completo, incluidas las líneas BEGIN y END.
TopicDisallowedLa clave no tiene permiso para enviar a esta app; por ejemplo, una clave Topic Specific que no incluye tu bundle ID, o una clave restringida al otro entorno.Crea una clave que cubra tu bundle ID y tu entorno, o usa una clave Team Scoped.
UnregisteredLa app se desinstaló o el token ya no está activo.No hay nada que corregir en las credenciales. Joryio deja de enviar a ese token.
«no device accepted the notification»El usuario no tiene ningún dispositivo iOS registrado para esta app.Abre en el dispositivo la app con el SDK integrado, permite las notificaciones y asegúrate de probar con el mismo usuario.
Se perdió el archivo de la claveApple solo permite una descarga.Crea una clave nueva (paso 1), introdúcela en Joryio y después revoca la anterior.
Se revocó una claveTodos los envíos con esa clave fallan.Crea una clave nueva e introdúcela en Joryio.

Seguridad y rotación​

  • Trata el archivo .p8 como un secreto: cualquiera que lo tenga, junto con tu Key ID y tu Team ID, puede enviar notificaciones a tus usuarios. No lo subas al control de versiones ni lo envíes por correo o chat.
  • Si crees que la clave se ha filtrado, crea una clave nueva, introdúcela en Joryio y después revoca la anterior: en Certificates, Identifiers & Profiles → Keys, haz clic en la clave, luego en Revoke y confirma. La revocación surte efecto de inmediato en todos los servicios que usan la clave.
  • Para rotar la clave sin interrupciones, sigue el mismo orden: primero la clave nueva en Joryio y después la revocación de la anterior. Apple limita cuántas claves puede tener un equipo por entorno, así que quizá tengas que revocar una clave sin uso antes de crear una nueva.