Cómo resolver las firmas de frameworks de CocoaPods en configuraciones del SDK de iOS

¿Cómo se solucionan los errores de firma de código en frameworks de CocoaPods al integrar un SDK de iOS? Diagnostica el destino de recursos (resource bundle) afectado y no ejecutable que desencadena el error de Development Team, y luego aplica una anulación de post_install en CocoaPods limitada al destino específico, en lugar de deshabilitar la firma de forma global en todos los paquetes.

En configuraciones afectadas de CocoaPods/Xcode, los destinos de paquetes de recursos generados pueden heredar ajustes de firma que provocan que Xcode solicite un equipo de desarrollo (Development Team). Resolver estos fallos de compilación requiere configurar ganchos personalizados de compilación post_install en el Podfile para deshabilitar los requisitos de firma en subdestinos de recursos no ejecutables, o bien ejecutar protocolos manuales de integración de XCFramework.

Por qué las reglas de firma de código de Xcode 15 y 16 interrumpen las compilaciones de CocoaPods del SDK de iOS

Cadena de herramientas de compilación de Xcode y firma de paquetes de recursos

A partir de Xcode 15 y continuando en Xcode 16, las modificaciones en el sistema de compilación de Xcode alteraron la forma en que los ajustes de firma de código se propagan hacia los subdestinos generados. En las configuraciones afectadas de Xcode y CocoaPods, los destinos de paquetes de recursos no ejecutables que empaquetan recursos como PrivacyInfo.xcprivacy, catálogos de activos o cadenas localizadas pueden heredar ajustes de firma de código que incitan a Xcode a solicitar un equipo de desarrollo (Development Team).

Este problema representa un desajuste en la integración del sistema de compilación dentro de la generación de destinos de CocoaPods, más que una política estricta de Apple que exija que cada paquete de recursos independiente y no ejecutable posea una firma de código independiente.

Anatomía del error de compilación: La firma para el destino requiere un equipo de desarrollo

Al integrar dependencias mediante CocoaPods, el gestor de dependencias genera un proyecto Pods.xcodeproj separado que contiene destinos aislados para cada pod y sus paquetes de recursos asociados. Durante la creación de archivos de almacenamiento (archive) o la compilación en el simulador, Xcode evalúa destinos con nombres similares a libOpoInstallSDK-OPPrivacy o Pods-YourApp-resource-bundle.

La compilación falla con un error característico:

Signing for "libOpoInstallSDK-OPPrivacy" requires a development team.
Select a development team in the Signing & Capabilities editor.

Debido a que CocoaPods genera estos subdestinos de forma dinámica al ejecutar pod install, configurar manualmente un equipo de desarrollo en la interfaz gráfica de Xcode es efímero. Volver a ejecutar pod install o compilar en un entorno de CI/CD limpio sobrescribe el archivo de proyecto, lo que provoca que el error de compilación vuelva a aparecer.

Cómo los subdestinos de CocoaPods heredan propiedades sin firmar para los paquetes de manifiesto de privacidad

Algunos podspecs de CocoaPods empaquetan manifiestos de privacidad mediante subdestinos de paquetes de recursos generados (por ejemplo, a través de declaraciones resource_bundles), mientras que otros incluyen los manifiestos dentro de frameworks suministrados o declaraciones directas de recursos.

En configuraciones afectadas de CocoaPods, un subdestino de paquete de recursos generado puede carecer de un valor DEVELOPMENT_TEAM utilizable o heredar ajustes de firma que hacen que Xcode solicite uno. En consecuencia, mientras que el destino principal de la aplicación se compila con un perfil de aprovisionamiento válido, el subdestino anidado del paquete de recursos puede activar la comprobación previa de firma de código de Xcode. Resolver este problema requiere una solución alternativa orientada a nivel de Podfile o una transición hacia la incorporación manual de frameworks.

Cómo configurar los ganchos de compilación del Podfile para solucionar los errores de firma de paquetes de frameworks

Comprender el gancho de ejecución post_install de CocoaPods

CocoaPods proporciona un gancho de ciclo de vida basado en Ruby llamado post_install dentro del Podfile. Este gancho se ejecuta inmediatamente después de que CocoaPods termina de generar el archivo de proyecto Pods.xcodeproj, pero antes de escribirlo en el disco. Al interceptar la generación del proyecto en esta etapa, los desarrolladores pueden iterar programáticamente a través de los destinos generados, inspeccionar sus tipos de producto y modificar los ajustes de configuración de compilación antes de que Xcode inicie la compilación.

Automatizar anulaciones de ajustes de compilación específicos para subdestinos de paquetes de recursos

Para resolver los errores de firma de paquetes tanto en máquinas de desarrollo locales como en agentes de compilación remotos de CI/CD, el gancho post_install puede inspeccionar los nombres y los tipos de producto de los destinos. En lugar de deshabilitar la firma de código de manera global en todos los paquetes de recursos de CocoaPods —lo que puede introducir riesgos de seguridad en dependencias de terceros—, los desarrolladores deben acotar la anulación exclusivamente a los paquetes de destino afectados.

Cuando un destino coincide con el tipo de producto de paquete de recursos de Apple (com.apple.product-type.bundle) y con los nombres de destino designados, el script borra el ajuste de compilación CODE_SIGN_IDENTITY y establece CODE_SIGNING_ALLOWED en NO. Para los destinos de paquetes de recursos no ejecutables afectados específicamente, deshabilitar la firma de código a nivel de destino sirve como una solución alternativa dirigida en el sistema de compilación, una vez validada con la aplicación archivada final y el flujo de trabajo de envío a la App Store.

El script de Ruby a continuación muestra cómo implementar esta anulación específica dentro del Podfile de tu proyecto:

# Podfile - Anulación de ajustes de compilación específicos para la firma de paquetes de recursos
# Coloca este gancho post_install al final del Podfile de tu proyecto

post_install do |installer|
  # Define nombres específicos de paquetes de destino que requieren exención de firma
  affected_bundle_targets = [
    'libOpoInstallSDK-OPPrivacy'
  ]

  installer.pods_project.targets.each do |target|
    next unless target.respond_to?(:product_type)
    next unless target.product_type == 'com.apple.product-type.bundle'
    next unless affected_bundle_targets.include?(target.name)

    target.build_configurations.each do |config|
      # Borrar la identidad de firma de código y deshabilitar la firma para los paquetes de recursos designados
      config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
      config.build_settings['CODE_SIGN_IDENTITY'] = ''
    end
  end
end

Verificar la compatibilidad de CI/CD en archivos de almacenamiento de Xcode y destinos de compilación del simulador

Después de añadir el gancho de compilación específico al Podfile, ejecuta pod install para aplicar las configuraciones actualizadas a Pods.xcodeproj. Las compilaciones para el simulador a menudo tienen requisitos de firma de distribución menos restrictivos que los archivos de almacenamiento para dispositivos (archives), pero los equipos de ingeniería deben validar los ajustes de los destinos afectados por separado en ejecuciones locales del simulador, ejecuciones de pruebas automatizadas de CI/CD y configuraciones de archivos de almacenamiento de lanzamiento de Xcode.

Comandos de inspección de diagnóstico para la verificación de la firma de código

Inspeccionar los ajustes de compilación de destinos y las identidades de firma de código

Al diagnosticar fallos de firma intermitentes en servidores de compilación, los desarrolladores pueden consultar la configuración de compilación de Xcode directamente mediante comandos de terminal. Esto permite verificar si el gancho post_install del Podfile eliminó con éxito los requisitos de firma de código para los subdestinos afectados. Ten en cuenta que los ajustes de compilación también se pueden inspeccionar directamente en destinos individuales dentro de Pods.xcodeproj en Xcode para verificar los valores efectivos específicos del destino.

Ejecuta el siguiente comando desde el directorio raíz del proyecto:

# Inspeccionar los ajustes de compilación de la firma de código para un espacio de trabajo objetivo
xcodebuild \
  -workspace YourApp.xcworkspace \
  -scheme YourApp \
  -configuration Release \
  -showBuildSettings | grep -E "(CODE_SIGN|DEVELOPMENT_TEAM)"

Auditar los paquetes de archivos de almacenamiento de Xcode y la integridad de la firma

Tras la generación del archivo de almacenamiento (archive), inspecciona el paquete de la aplicación compilada para confirmar que los manifiestos de privacidad estén ubicados correctamente y que los binarios del framework mantengan la integridad de su firma.

Ejecuta estos comandos de diagnóstico en la terminal sobre un archivo IPA extraído (dentro de Payload/YourApp.app) o dentro de una ruta de .xcarchive de Xcode (Products/Applications/YourApp.app):

# Inspeccionar la presencia del manifiesto de privacidad dentro de un paquete IPA extraído
find Payload/YourApp.app -name "PrivacyInfo.xcprivacy" -print

# Para un framework incrustado dinámicamente, verificar la integridad de la firma codesign:
codesign -dv --verbose=4 Payload/YourApp.app/Frameworks/OpoInstallSDK.framework

# Ejecutar la verificación profunda de la firma en el paquete de la aplicación compilada final
# Nota: Utiliza --deep estrictamente para la inspección de verificación; no lo uses durante la ejecución de la firma de código
codesign --verify --deep --strict --verbose=2 Payload/YourApp.app

La ejecución de esta secuencia de inspección establece un bucle de diagnóstico completo (reproducir → inspeccionar → parchear → verificar) para garantizar que las compilaciones de lanzamiento cumplan con la validación de App Store Connect.

Cómo importar el SDK de iOS mediante el gestor de dependencias CocoaPods

Configurar el Podfile del proyecto de destino con pod ‘libOpoInstallSDK’

La integración de OpoInstall, una plataforma de atribución móvil y deep linking, a través de CocoaPods representa el enfoque estándar de gestión de dependencias para aplicaciones de iOS. La distribución actual de CocoaPods gestiona el enlace del SDK y los recursos empaquetados de acuerdo con su podspec. Incluye use_frameworks! cuando lo requiera la integración actual de CocoaPods del SDK o la arquitectura del proyecto.

Para añadir la dependencia, abre el Podfile raíz y especifica la dependencia del destino:

target 'YourAppTarget' do
  use_frameworks!
  
  # Importar el SDK de atribución de iOS de OpoInstall
  pod 'libOpoInstallSDK'
end

Ejecutar la ingesta de dependencias y validar la integridad del espacio de trabajo

Ejecuta el comando de instalación desde el directorio raíz del proyecto usando la terminal:

pod install --repo-update

Tras completarse con éxito, CocoaPods genera o actualiza el archivo .xcworkspace. Los desarrolladores deben cerrar el archivo .xcodeproj estándar y abrir el archivo .xcworkspace en Xcode. Inspecciona la carpeta del proyecto Pods para verificar que libOpoInstallSDK y su destino de paquete OPPrivacy asociado aparezcan bajo la lista de destinos de Pods.

Inicializar el motor del SDK en arquitecturas de proyectos en Swift

Después de vincular el framework, inicializa el SDK dentro del delegado del ciclo de vida de la aplicación. Inicializa el SDK en el punto del ciclo de vida documentado para la versión exacta del SDK; los ejemplos públicos actuales lo inicializan desde application(_:didFinishLaunchingWithOptions:) para capturar los parámetros de Universal Links en arranque en frío y las cargas útiles de instalación dinámica. Verifica los nombres de los protocolos del delegado y de los tipos de modelos de datos (por ejemplo, OpoinstallData o OpoInstallData) con la versión exacta del SDK de OpoInstall enviada.

Los desarrolladores pueden revisar la documentación completa del SDK de atribución de iOS para obtener definiciones detalladas de los métodos del delegado y firmas de devolución de llamada de parámetros dinámicos.

El fragmento de implementación a continuación ilustra cómo ajustarse a OpoInstallDelegate y activar la inicialización del SDK en bases de código modernas en Swift:

// AppDelegate.swift - Inicialización del SDK de iOS de OpoInstall
// Colócalo dentro del Delegado de la Aplicación de iOS

import UIKit
import libOpoInstallSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        # Inicializar el SDK de OpoInstall con el oyente del delegado
        OpoInstallSDK.initWith(self)
        
        return true
    }

    // Método de devolución de llamada: Gestiona los parámetros recuperados cuando la app se inicia mediante un deep link
    func getWakeUpParams(_ appData: OpoinstallData?) {
        if let customData = appData?.data {
            print("OpoInstall SDK: Custom Launch Parameters = \(customData)")
        }
        if let channelCode = appData?.channelCode {
            print("OpoInstall SDK: Channel ID = \(channelCode)")
        }
    }
}

Flujo de trabajo de importación manual de frameworks para destinos de proyectos de iOS

Cuándo elegir la importación manual en lugar de CocoaPods en entornos de compilación empresariales

Si bien CocoaPods simplifica la gestión de paquetes, ciertos entornos de desarrollo empresariales imponen estrictas restricciones de seguridad o en el entorno de compilación. La integración manual de frameworks se prefiere cuando:

• Aislamiento de repositorios: Los sistemas de compilación restringen las conexiones salientes a Internet, lo que impide la recuperación de dependencias mediante pod install durante la compilación.
• Velocidad de la canalización de compilación: Eliminar los pasos de análisis y ejecución de scripts de CocoaPods reduce los tiempos de compilación de CI/CD.
• Control directo de binarios: Las políticas de cumplimiento de seguridad exigen un análisis binario estático en artefactos .xcframework exactos antes de su inclusión en el proyecto.

Descargar e incrustar artefactos XCFramework

Para importar manualmente el SDK sin gestores de dependencias, descarga el paquete más reciente del framework del SDK de iOS. Descomprime el archivo de distribución para localizar el directorio compilado OpoInstallSDK.xcframework.

Para identificar si un segmento (slice) de XCFramework es estático o dinámico antes de incrustarlo, ejecuta el comando file en la terminal:

# Consultar el tipo de segmento de arquitectura binaria
file OpoInstallSDK.xcframework/ios-arm64/OpoInstallSDK.framework/OpoInstallSDK

Sigue estos pasos para integrar el binario en Xcode:

• Paso 1: Abre tu proyecto de aplicación principal en Xcode.
• Paso 2: Arrastra el directorio OpoInstallSDK.xcframework al Navegador de Proyectos de Xcode bajo el grupo de frameworks del destino principal.
• Paso 3: En el diálogo emergente, marca Copy items if needed y selecciona tu destino de aplicación principal bajo Add to targets.

Configurar Link Binary With Libraries y las rutas de búsqueda de frameworks

Navega a la configuración del destino de tu aplicación dentro de Xcode:

• Build Phases: Expande la sección Link Binary With Libraries. Confirma que OpoInstallSDK.xcframework aparezca en la lista.
• Build Settings: Busca Framework Search Paths (FRAMEWORK_SEARCH_PATHS). Asegúrate de que la ruta del directorio que contiene el framework añadido manualmente esté presente.
• Dependencias del sistema: Añade únicamente los frameworks del sistema de Apple documentados por la versión exacta del SDK que estás integrando (por ejemplo, AdSupport.framework o WebKit.framework). No añadas frameworks heredados no verificados.

Establecer políticas de incrustación y firma para binarios dinámicos frente a estáticos

Selecciona el destino de la aplicación y navega a la pestaña General. Localiza la sección Frameworks, Libraries, and Embedded Content:

Frameworks dinámicos: Establece la opción de incrustación en Embed & Sign. Los frameworks dinámicos deben residir dentro del directorio Frameworks del paquete de la aplicación final para que el enlazador dinámico (dyld) pueda cargarlos en tiempo de ejecución, y Xcode aplicará la firma de código de tu equipo de desarrollo durante el archivado.
Frameworks estáticos sin recursos: Enlazar el binario es suficiente, e incrustar el framework suele ser innecesario porque el código estático se compila directamente en el ejecutable principal de la aplicación.
Frameworks estáticos con recursos (incluidos manifiestos de privacidad): Sigue las directrices de distribución del proveedor del SDK. Para frameworks estáticos de Xcode 15+ construidos para empaquetar recursos incrustados, Apple documenta añadir el framework con Embed & Sign; Xcode omite el binario ejecutable ya enlazado estáticamente mientras preserva y firma el paquete del framework y sus recursos incrustados.

Solución de problemas de conflictos de firma de PrivacyInfo.xcprivacy en CocoaPods

Requisitos del Manifiesto de Privacidad de Apple para dependencias de frameworks de terceros

Los SDKs de terceros pueden necesitar incluir un manifiesto PrivacyInfo.xcprivacy según su uso de API, prácticas de recopilación de datos, comportamiento de rastreo y si el SDK aparece en la lista publicada de Apple de SDKs sujetos a requisitos explícitos de manifiesto.

La distribución actual de OpoInstall incluye un manifiesto PrivacyInfo.xcprivacy; los desarrolladores deben verificar sus declaraciones con la versión específica del SDK enviada y las directrices de envío actuales de Apple antes de realizar el archivado.

Resolver conflictos de recursos duplicados del Manifiesto de Privacidad

Al compilar una aplicación que incorpora múltiples dependencias de terceros, Xcode descubre manifiestos de privacidad en toda la aplicación archivada y en los paquetes de SDK vinculados, agregando sus declaraciones al generar el Informe de Privacidad de Xcode para auditar las declaraciones de privacidad incorporadas.

Si un proyecto incluye incorrectamente archivos de manifiesto de privacidad duplicados directamente dentro de la fase Copy Bundle Resources del destino principal, Xcode puede emitir una advertencia o error de compilación:

Multiple commands produce '.../PrivacyInfo.xcprivacy'

Para resolver este conflicto:

• Ubicación del manifiesto del framework: Para un XCFramework de iOS, PrivacyInfo.xcprivacy debe residir dentro de cada variante de framework aplicable específica de la plataforma (por ejemplo, OpoInstallSDK.xcframework/ios-arm64/OpoInstallSDK.framework/PrivacyInfo.xcprivacy), en lugar de colocarse en el directorio raíz del contenedor del XCFramework.
• Recursos de la aplicación principal: Mantén las declaraciones de privacidad de la aplicación host en los recursos del destino principal, permitiendo al mismo tiempo que las variantes del framework del SDK gestionen sus respectivos archivos de manifiesto de forma interna.

Verificar las declaraciones de API de razones requeridas dentro de PrivacyInfo.xcprivacy

Inspecciona el contenido del manifiesto de privacidad para verificar que todas las categorías de API declaradas coincidan con las especificaciones oficiales de API de razones requeridas (Required Reason API) de Apple. Abre PrivacyInfo.xcprivacy como una lista de propiedades (Property List) o XML sin procesar en Xcode. Las declaraciones deben corresponder estrictamente a los usos de API necesarios:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>CA92.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Incluye únicamente las categorías de API y los códigos de razones aprobados que correspondan a los requisitos reales de implementación del SDK.

Validar envíos finales de IPA a App Store Connect

Antes de enviar una actualización de aplicación a App Store Connect, valida el archivo IPA compilado localmente:

• Paso 1: En Xcode, selecciona Product > Archive.
• Paso 2: Al finalizar el archivo, haz clic en Validate App dentro de la ventana Organizer.
• Paso 3: Xcode comprueba las firmas de los frameworks incrustados, los derechos de aprovisionamiento (provisioning entitlements) y los esquemas de los manifiestos de privacidad frente a los servidores de validación de Apple.

Una validación exitosa indica que el archivo superó esa etapa de validación previa al envío; sirve como un paso necesario de verificación de compilación antes del envío a TestFlight o producción.

Análisis comparativo de CocoaPods frente a la importación manual de frameworks de iOS

Resumen y marco de decisiones

La importación eficiente del SDK de iOS requiere seleccionar el mecanismo de dependencia adecuado para la cadena de herramientas de tu proyecto, mitigando al mismo tiempo la estricta firma de código de Xcode. Utilizar CocoaPods con un gancho post_install acotado puede resolver los fallos de firma en los paquetes de recursos afectados, mientras que la incorporación manual de XCFramework ofrece un control directo sobre los artefactos de compilación.

A medida que Apple continúa perfeccionando las reglas de verificación de App Store Connect, mantener las dependencias del cliente en conformidad con los estándares del manifiesto de privacidad sigue siendo fundamental. Al desplegar versiones actualizadas del SDK y mantener ganchos automatizados en el Podfile, los equipos de ingeniería reducen los bloqueos de compilación recurrentes y mejoran la coherencia de la integración.

Los desarrolladores listos para inicializar la clave de su proyecto pueden registrarse en la consola de desarrolladores de OpoInstall o revisar la referencia de implementación de atribución móvil completa para obtener directrices adicionales sobre la plataforma.

Materiales relacionados

• Conceptos: SDK de iOS, Identidad de Firma de Código, Firma de Paquetes de Recursos, Agregación de Manifiestos de Privacidad

• Tecnologías: CocoaPods, Cadena de herramientas de compilación de Xcode, XCFramework, Swift Package Manager

• Estándares: Directrices de envío a Apple App Store Connect, Requisitos de Manifiestos de Privacidad de Apple

• APIs: APIs de Delegados del SDK de iOS de OpoInstall, APIs de UIPasteboard de Apple, APIs de dominios asociados de Universal Links

• Documentación oficial y referencias:

  • Guía para desarrolladores de Apple sobre archivos de manifiesto de privacidad

  • Documentación de Apple sobre los requisitos para SDKs de terceros

  • Nota técnica para desarrolladores de Apple sobre APIs de razones requeridas

  • Guía de Xcode de Apple sobre cómo crear un framework estático

  • Referencia de sintaxis de CocoaPods para ganchos del Podfile