Instalar y configurar el SDK de Adapty para Kotlin Multiplatform

El SDK de Adapty incluye dos módulos clave para una integración fluida en tu app móvil:

• Core Adapty: Este SDK esencial es necesario para que Adapty funcione correctamente en tu app.
• AdaptyUI (io.adapty:adapty-kmp-ui): Este módulo es necesario si utilizas el Adapty Paywall Builder con la capa de renderizado de Compose Multiplatform (view.present()). Si tu proyecto no usa Compose Multiplatform, puedes usar createNativePaywallView y createNativeOnboardingView del módulo principal en su lugar.

Para un recorrido completo de implementación, también puedes ver el vídeo:

Requisitos

El SDK de Adapty para Kotlin Multiplatform es compatible con Xcode 16.2 y versiones posteriores.

Instala el SDK de Adapty con Gradle

La instalación del SDK de Adapty con Gradle es necesaria tanto para apps Android como iOS.

Elige el método de configuración de dependencias:

• Gradle estándar: añade las dependencias a tu build.gradle a nivel de módulo
• Si tu proyecto usa archivos .gradle.kts, añade las dependencias a tu build.gradle.kts a nivel de módulo
• Si usas catálogos de versiones, añade las dependencias a tu archivo libs.versions.toml y luego referéncialas en build.gradle.kts

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation libs.adapty.kmp
            }
        }
    }
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

// libs.versions.toml
[versions]
..
adapty-kmp    = "<the latest SDK version>"

[libraries]
..
adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" }

// build.gradle.kts

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

allprojects {
    repositories {
        ...
        mavenCentral()
    }
}

dependencyResolutionManagement {
    ...
    repositories {
        ...
        google()
        mavenCentral()
    }
}

Activar el SDK de Adapty

Configuración básica

Añade la inicialización lo antes posible, normalmente en tu código Kotlin compartido para ambas plataformas.

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .build()

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }

Para obtener tu Public SDK Key:

1. Ve al Adapty Dashboard y navega a App settings → General.
2. En la sección Api keys, copia la Public SDK Key (NO la Secret Key).
3. Reemplaza "YOUR_PUBLIC_SDK_KEY" en el código.

Ahora configura los paywalls en tu app:

• Si usas Adapty Paywall Builder, primero activa el módulo AdaptyUI a continuación, y luego sigue la guía de inicio rápido del Paywall Builder.
• Si construyes tu propia interfaz de paywall, consulta la guía de inicio rápido para paywalls personalizados.

Activa el módulo AdaptyUI del SDK de Adapty

Si tienes previsto activar el módulo AdaptyUI para usar el Adapty Paywall Builder, asegúrate de establecer .withActivateUI(true) en tu configuración.

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withActivateUI(true)           // true for activating the AdaptyUI module
    .build()

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }

Configurar Proguard (Android)

Antes de lanzar tu app en producción, es posible que necesites añadir -keep class com.adapty.** { *; } a tu configuración de Proguard.

Configuración opcional

Registro de actividad

Configurar el sistema de registro

Adapty registra errores e información importante para ayudarte a entender qué está pasando. Los niveles disponibles son los siguientes:

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withLogLevel(AdaptyLogLevel.VERBOSE) // recommended for development
     .build()

Políticas de datos

Deshabilitar la recopilación y el uso compartido de la dirección IP

Al activar el módulo de Adapty, establece ipAddressCollectionDisabled en true para deshabilitar la recopilación y el uso compartido de la dirección IP del usuario. El valor predeterminado es false.

Usa este parámetro para mejorar la privacidad del usuario, cumplir con las normativas regionales de protección de datos (como GDPR o CCPA) o reducir la recopilación de datos innecesaria cuando las funciones basadas en IP no son necesarias para tu app.

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withIpAddressCollectionDisabled(true)
     .build()

Deshabilitar la recopilación y el uso compartido del ID publicitario

Al activar el módulo de Adapty, establece appleIdfaCollectionDisabled (iOS) o googleAdvertisingIdCollectionDisabled (Android) en true para deshabilitar la recopilación de identificadores publicitarios. El valor predeterminado es false. Usa este parámetro para cumplir con las políticas de App Store/Play Store, evitar que se muestre el aviso de App Tracking Transparency o si tu app no necesita atribución publicitaria ni analíticas basadas en identificadores de publicidad.

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withGoogleAdvertisingIdCollectionDisabled(true)        // Android only
     .withAppleIdfaCollectionDisabled(true)                  // iOS only
     .build()

Configurar la caché de medios para AdaptyUI

Por defecto, AdaptyUI almacena en caché los medios (como imágenes y vídeos) para mejorar el rendimiento y reducir el uso de red. Puedes personalizar los ajustes de caché proporcionando una configuración personalizada.

Usa mediaCache para sobrescribir los ajustes de caché por defecto:

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withMediaCacheConfiguration(
        AdaptyConfig.MediaCacheConfiguration(
            memoryStorageTotalCostLimit = 200 * 1024 * 1024, // 200 MB
            memoryStorageCountLimit = Int.MAX_VALUE,
            diskStorageSizeLimit = 200 * 1024 * 1024 // 200 MB
        )
    )
    .build()

Habilitar niveles de acceso locales (Android)

Por defecto, los niveles de acceso locales están desactivados para Android. Para habilitarlos, establece withLocalAccessLevelAllowed en true:

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withGoogleLocalAccessLevelAllowed(true)
    .build()

Borrar datos al restaurar desde copia de seguridad

Cuando withAppleClearDataOnBackup se establece en true, el SDK detecta cuándo la app se restaura desde una copia de seguridad de iCloud y elimina todos los datos almacenados localmente por el SDK, incluida la información de perfil en caché, los detalles de productos y los paywalls. El SDK se inicializa entonces con un estado limpio. El valor predeterminado es false.

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAppleClearDataOnBackup(true)
    .build()

Solución de problemas

Reglas de copia de seguridad en Android (configuración de Auto Backup)

Algunos SDKs (incluido Adapty) incluyen su propia configuración de Android Auto Backup. Si utilizas varios SDKs que definen reglas de copia de seguridad, el fusionador de manifiestos de Android puede fallar con un error relacionado con android:fullBackupContent, android:dataExtractionRules o android:allowBackup.

Síntomas típicos del error: Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

Para resolverlo, necesitas:

• Indicar al fusionador de manifiestos que use los valores de tu app para los atributos relacionados con la copia de seguridad.

• Crear archivos de reglas de copia de seguridad que combinen las reglas de Adapty con las de otros SDKs.

1. Añade el namespace tools a tu manifiesto

En tu archivo AndroidManifest.xml, asegúrate de que la etiqueta raíz <manifest> incluya tools:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Sobreescribe los atributos de copia de seguridad en <application>

En el mismo archivo AndroidManifest.xml, actualiza la etiqueta <application> para que tu app proporcione los valores definitivos e indique al fusionador de manifiestos que reemplace los valores de las librerías:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Si algún SDK también define android:allowBackup, inclúyelo en tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Crea los archivos de reglas de copia de seguridad combinadas

Crea archivos XML en el directorio res/xml/ de tu proyecto Android que combinen las reglas de Adapty con las de otros SDKs. Android utiliza distintos formatos de reglas de copia de seguridad según la versión del sistema operativo, por lo que crear ambos archivos garantiza la compatibilidad con todas las versiones de Android que admite tu app.

Para Android 12 y superior (usa el nuevo formato de reglas de extracción de datos):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Para Android 11 e inferior (usa el formato legado de contenido de copia de seguridad completa):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Las compras fallan al volver desde otra app en Android

Si la Activity que inicia el flujo de compra utiliza un launchMode no predeterminado, Android puede recrearla o reutilizarla de forma incorrecta cuando el usuario regresa desde Google Play, una aplicación bancaria o un navegador. Esto puede provocar que el resultado de la compra se pierda o se trate como cancelado.

Para garantizar que las compras funcionen correctamente, utiliza únicamente los modos de lanzamiento standard o singleTop para la Activity que inicia el flujo de compra, y evita cualquier otro modo.

En tu AndroidManifest.xml, asegúrate de que la Activity que inicia el flujo de compra esté configurada como standard o singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />