¿Cómo automatizar el seguimiento de referidos móviles para compartir en web?

¿Cómo configurar el seguimiento automatizado de referidos para móviles? Configurar el seguimiento automatizado de referidos requiere integrar un SDK de atribución, adjuntar un token de referido opaco (shareCode) al enlace de compartición web, capturarlo en la página de destino y utilizar enlaces profundos diferidos compatibles con la plataforma para intentar la recuperación de parámetros en el primer inicio de la aplicación.

El seguimiento automatizado de referidos es un marco de ingeniería que atribuye programáticamente las instalaciones de aplicaciones móviles a las acciones de compartición de usuarios existentes. Al transmitir un identificador de invitado opaco (shareCode) a través de páginas de destino web e intentar resolver este contexto en el lanzamiento inicial de la aplicación, el seguimiento automatizado de referidos reduce la entrada manual de códigos promocionales y permite la atribución a través de contenedores de navegador integrados en las aplicaciones.

Descripción General de la Arquitectura: Cómo el Seguimiento Automatizado de Referidos Conecta las Comparticiones Sociales con las Instalaciones de la App

El Desglose Mecánico de los Sistemas de Referidos Heredados: Por Qué los Códigos Promocionales Manuales Reducen la Velocidad del Embudo

Los programas tradicionales de referidos móviles dependen de códigos promocionales alfanuméricos manuales. Bajo este flujo de trabajo heredado, un usuario existente genera un código de invitación (como INVITE2026), copia el texto manualmente y se lo envía a un colega a través de SMS o mensajería social. El usuario invitado debe entonces descargar la aplicación desde una tienda de aplicaciones, completar el registro, ubicar un campo de entrada de código promocional dedicado y transcribir con precisión la cadena de caracteres.

Este proceso manual introduce una fricción sustancial en todo el embudo de adquisición:

• Abandono Cognitivo y Mecánico: Los usuarios frecuentemente olvidan copiar el código de cupón, no logran encontrar la entrada de canje dentro de los menús profundos de incorporación o abandonan el proceso cuando los códigos fallan debido a errores de capitalización o transcripción.
• Fuga de Canales y Raspado de Códigos: Los códigos alfanuméricos se extraen fácilmente y se publican en agregadores de cupones públicos o foros. Esto rompe la auténtica relación entre pares, permitiendo que los usuarios orgánicos no referidos reclamen recompensas mientras diluyen la economía unitaria de la campaña.
• Puntos Ciegos de Medición: Depender exclusivamente de códigos promocionales manuales deja hitos intermedios del embudo (como impresiones de enlaces, clics en vistas web sociales y tasas de envío a la tienda) sin medir a menos que se implemente una instrumentación analítica separada.

El Canal de Compartición Programática: Acción del Invitador, Configuración Web, Transferencia a la Tienda y Resolución del Día 0

El seguimiento automatizado de referidos reemplaza la transcripción manual con una tubería continua y programática de paso de parámetros. En lugar de distribuir un enlace de tienda sin parametrizar junto con un cupón de texto desconectado, la aplicación agrupa la identidad del invitador directamente en una URL de compartición web interactiva.

El ciclo de vida técnico opera en cuatro etapas discretas:

[Usuario Existente Invita a un Amigo] ──> Llama a shareTelemetry.reportIntent(shareCode, Platform)
              │
              ▼
[Genera Enlace Web Dinámico] ───> Agrega ?shareCode=usr_9f82a1b4 a la URL de Destino
              │
              ▼
[Compartido dentro de WeChat/Line] ────> El Amigo Toca el Enlace en Webview Sandboxed
              │
              ▼
[Configuración y Transferencia Web JS SDK] ─> Almacena Contexto en Caché y Ejecuta Lanzamiento de App / Descarga en Tienda
              │
              ▼
[Primer Lanzamiento de App en Dispositivo] ───> SDK Nativo Consulta Recuperación de Parámetros
              │
              ▼
[Vinculación con Backend de la Aplicación] ──> El Backend Valida el Token y Crea una Vinculación Pendiente
              │
              ▼
[Hito de Activación Verificado] ─> El Backend Desembolsa la Recompensa al Completar el Hito

Cuando el usuario invitado abre el enlace, la página de destino web alojada ejecuta un SDK de Web JS que extrae el token del invitador (shareCode) y prepara el contexto del referido. Cuando el usuario procede a instalar y abrir la aplicación nativa, el SDK del cliente recupera la carga útil preparada durante el lanzamiento inicial, lo que permite que el backend de la aplicación vincule automáticamente la relación de referido sin requerir la entrada manual de datos de ninguno de los participantes.

Recuperación Posterior al Primer Lanzamiento en la Tienda: Limitaciones Específicas de la Plataforma

Después de que un usuario instala una aplicación desde una tienda de aplicaciones, la recuperación de parámetros de referidos depende de la plataforma y del mecanismo implementado por la aplicación o el SDK de atribución. Pasar un shareCode a través de una URL web no garantiza por sí solo que el parámetro esté disponible para la aplicación recién instalada.

• Android / Google Play: Google Play Install Referrer puede proporcionar metadatos de referidos compatibles asociados con una instalación de Play Store. La aplicación debe configurar y probar la carga útil real del referente y verificar que los parámetros esperados sobrevivan al flujo de redirección y e instalación. Los SDKs de atribución de terceros pueden utilizar mecanismos adicionales, que deben documentarse por separado.
• iOS / App Store: La App Store no transfiere automáticamente los parámetros de consulta arbitrarios de la página de destino a una aplicación instalada. Los Enlaces Universales admiten el enrutamiento directo cuando la aplicación ya está instalada y la configuración del dominio asociado es válida; por sí solos, no garantizan la recuperación de parámetros diferidos después de una nueva instalación.
• SDKs de Atribución: Utilice únicamente los mecanismos de recuperación documentados para la versión exacta del SDK y la plataforma que se esté implementando. Verifique la implementación, la recopilación de datos y las implicaciones de privacidad en lugar de asumir que un SDK puede recuperar todos los parámetros de referidos en cada navegador y ruta de instalación.

Si el contexto del referido no se puede recuperar a través de un mecanismo compatible, permita que el usuario complete la incorporación y registre la instalación como no atribuida. No infiera ni fabrique una relación de referido a partir de una coincidencia no verificada.

Atribución en iOS y Límite de Privacidad

Las implementaciones de referidos en iOS no deben depender de la toma de huellas digitales del dispositivo (fingerprinting) prohibida para identificar a un usuario o dispositivo en aplicaciones o sitios web. Los requisitos de privacidad y uso de datos de Apple prohíben derivar un identificador único del dispositivo, navegador, configuración, ubicación o señales de red para este propósito. La autorización de Transparencia en el Seguimiento de Apps (ATT) no hace que el fingerprinting prohibido sea permisible.

Utilice Enlaces Universales para el enrutamiento directo y verificado de aplicaciones cuando la aplicación esté instalada. Para la recuperación de referidos posterior a la instalación, utilice un mecanismo documentado cuyo comportamiento haya sido revisado para la versión del SDK implementada y los requisitos aplicables de Apple. Revise las divulgaciones de privacidad del SDK y las declaraciones de API de motivo requerido cuando corresponda, pero no trate la presencia de un Manifiesto de Privacidad como prueba de que la implementación de atribución cumple con las normativas.

Si el SDK seleccionado se basa en un método de coincidencia que no se puede verificar como permitido, no recomiende ese método para la implementación en iOS. Obtenga aclaraciones del proveedor del SDK y elija una alternativa que cumpla con las normas. Cuando ningún mecanismo permitido pueda establecer la relación de referido de manera confiable, preserve el flujo de incorporación normal y marque la instalación como no atribuida.

Referencia: Privacidad del usuario y uso de datos de Apple.

Véase También: Seguimiento de Referidos ──> Instalación de Parámetros de la App

Paso 1: Instrumentación de la API de Informes de Compartición del Lado del Cliente

Inicialización del SDK de Atribución Nativo en los Puntos de Entrada de Android e iOS

Antes de que una aplicación pueda informar sobre la actividad de compartición o recuperar el contexto de referidos entrantes, el SDK móvil nativo debe inicializarse temprano en el ciclo de vida de la aplicación.

En Android, la inicialización pertenece al método onCreate() de la subclase Application personalizada, asegurando que los oyentes de atribución y las estructuras de memoria principales se establezcan antes de que se monten los componentes de la interfaz de usuario en primer plano. En iOS, la inicialización ocurre dentro del delegado de ejecución application(_:didFinishLaunchingWithOptions:).

Los desarrolladores pueden obtener los paquetes oficiales del SDK móvil directamente desde el centro de descargas del SDK de OpoInstall.

Invocación del Método de Informes de Compartición Antes de Activar las Hojas de Compartir del Sistema Operativo Nativo

La aplicación debe registrar la intención de compartir antes de abrir la interfaz de compartición de la plataforma. Implemente esto a través de un servicio de telemetría propiedad de la aplicación o un método del SDK de atribución verificado con la versión exacta del SDK en uso. El siguiente ejemplo utiliza una abstracción shareTelemetry.reportIntent(...) propiedad de la aplicación; no es una API oficial de OpoInstall. El adaptador debe implementar la solicitud de red real, el manejo de errores y el comportamiento de devolución de llamada (callback) para la aplicación implementada.

Para mantener una telemetría limpia, los equipos de ingeniería deben diferenciar entre cinco eventos distintos en el ciclo de vida de la compartición:

• Intención de Compartir Iniciada (share_intent_initiated): La interfaz de usuario de la aplicación cliente registra que el usuario hizo clic en la acción de invitación.
• Compartición Enviada (share_dispatched): La aplicación cliente pasa la carga útil a una plataforma de destino identificada (por ejemplo, lanzando una intención social explícita) o abre el selector de compartición del sistema.
• Compartición Completada (share_completed): El SDK social de terceros devuelve una devolución de llamada de finalización autenticada que confirma que el mensaje se publicó o envió (aplicable solo cuando se utilizan SDKs de plataformas de terceros dedicados con soporte de devolución de llamada).
• Referido Hacido Clic (referral_click): El destinatario abre la página de destino web, lo que activa el registro de entrada del lado web.
• Referido Vinculado (referral_bound): El destinatario completa el registro de la cuenta, y el backend verifica el shareCode candidato y escribe la relación de referido en la base de datos.

Registrar la telemetría de compartición captura la intención del usuario de compartir. Esto permite que los canales de análisis indexen el shareCode del invitador frente al canal de plataforma designado, preparando al sistema para correlacionar las visitas posteriores a la página de destino web.

Especificación de Identificadores de Plataforma: Mapeo de Canales Sociales

Los siguientes identificadores son meros ejemplos ilustrativos. Utilice la enumeración exacta de canales admitida por la versión del SDK implementada y valide cada identificador con su referencia de API oficial:

• Redes de Mensajería Cerradas: WechatSession (Chat Directo de WeChat), WechatTimeline (Momentos de WeChat), Line, WhatsApp, FacebookMessenger.
• Feeds Sociales y Microblogs Públicos: Twitter, Facebook, Instagram, Weibo, Douyin, TikTok.
• Transportes Directos del Sistema Operativo: Sms, Email, Copy (Copia de Enlace al Portapapeles) y Other (Hoja de Compartir del Sistema).

Cuando la aplicación lanza una hoja de compartición del sistema genérica donde la selección de destino final del usuario no se puede determinar de antemano, el evento debe clasificarse como Other en lugar de codificar rígidamente una red social específica.

Estructuración de Tokens de Identidad del Invitador: Mejores Prácticas para Formatear el shareCode

El shareCode funciona como un token de negocio a nivel de aplicación que conecta la nueva instalación con la cuenta de referencia. Si bien los desarrolladores pueden usar cadenas alfanuméricas arbitrarias, adherirse a las mejores prácticas estructurales evita la corrupción de parámetros:

Tokens Opacos Emitidos por el Servidor: El shareCode debe ser un token de referido opaco emitido por el servidor (por ejemplo, un token seguro para URL o UUID como usr_9f82a1b4) en lugar de un ID de autoincremento de base de datos sin procesar enumerable (1024). El backend de la aplicación resuelve este token para la cuenta del invitador, aplicando límites de tiempo de expiración y de velocidad.
Restricciones de Longitud: Mantenga el token compacto (se recomienda menos de 64 caracteres; estrictamente \le 128 caracteres) para evitar inflar las longitudes de las URL o activar el truncamiento de cadenas en las aplicaciones de mensajería.
Conjuntos de Caracteres Seguros: Restrinja los caracteres a valores alfanuméricos seguros para URL, guiones y guiones bajos ([A-Za-z0-9_-]). Evite delimitadores sin procesar como &, =, ? o espacios que alteren el análisis de URI.

En Android 11 (nivel de API 30) y versiones posteriores, consultar si hay paquetes sociales de terceros instalados requiere declarar los elementos <queries> correspondientes dentro de AndroidManifest.xml según la Guía para Desarrolladores de Android de Google sobre Visibilidad de Paquetes en Android 11. El patrón de implementación a continuación ilustra cómo declarar la visibilidad de los paquetes, manejar tiempos de espera (timeouts) de informes de compartición no bloqueantes, gestionar restablecimientos de estado seguros para el ciclo de vida y enviar intenciones sociales explícitas con respaldos de portapapeles:

<!-- Configuración de Android e Implementación de Compartición del Lado del Cliente -->
<!-- Parte 1: Visibilidad de Paquetes en AndroidManifest.xml y Declaraciones de la Aplicación -->
<!-- Archivo: app/src/main/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

    <!-- Declaraciones de visibilidad de paquetes explícitas requeridas para Android 11+ (API 30+) -->
    <queries>
        <package android:name="com.tencent.mm" />
        <package android:name="jp.naver.line.android" />
    </queries>

    <application
        android:name=".CustomApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.AppCompat.Light.NoActionBar">
        
        <activity
            android:name=".InviteActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

// Entrada del Ciclo de Vida de la Aplicación Android
// Parte 2: CustomApplication.kt (Inicialización del Ciclo de Vida del SDK)
// Archivo: app/src/main/java/com/example/app/CustomApplication.kt

package com.example.app

import android.app.Application
import com.opoinstall.api.OpoInstall

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Inicializa el cliente principal de OpoInstall en el hilo principal antes de montar la actividad
        OpoInstall.initialize(this)
    }
}

// Implementación de la Actividad de Compartición en Android
// Parte 3: InviteActivity.kt (Telemetría de la Aplicación y Envío Dirigido con Respaldo en el Portapapeles)
// Archivo: app/src/main/java/com/example/app/InviteActivity.kt

package com.example.app

import android.content.ClipData
import android.content.ClipboardManager
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.net.Uri
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.util.Log
import android.widget.Button
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import java.util.concurrent.atomic.AtomicBoolean

class InviteActivity : AppCompatActivity() {

    companion object {
        private const val TAG = "ReferralShareTracking"
        // Ejemplo de punto de finalización de redirección propiedad de la aplicación; reemplazar con una ruta HTTPS implementada
        private const val BASE_INVITE_HOST = "promo.example.com"
        private const val BASE_INVITE_PATH = "invite.html"
        
        // Paquetes de plataformas de destino para el enrutamiento de intenciones explícitas
        private const val PACKAGE_WECHAT = "com.tencent.mm"
        private const val PACKAGE_LINE = "jp.naver.line.android"
        
        // Tiempo de espera de ejemplo definido por la aplicación; ajustar y probar para el servicio de telemetría real
        private const val SHARE_TIMEOUT_MS = 800L
    }

    // Protección antirrebote para evitar invocaciones rápidas y concurrentes de intenciones de compartición
    private val isSharingInProgress = AtomicBoolean(false)

    // Abstracción del adaptador de telemetría propiedad de la aplicación
    private val shareTelemetry = ShareTelemetryService()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_invite)

        val btnShareWeChat = findViewById<Button>(R.id.btn_share_wechat)
        val btnShareLine = findViewById<Button>(R.id.btn_share_line)
        val btnShareGeneric = findViewById<Button>(R.id.btn_share_generic)

        // Token simulado ilustrativo: En producción, recupere el token emitido por el servidor de una sesión autenticada
        val currentInviterToken = "usr_9f82a1b4"

        btnShareWeChat.setOnClickListener {
            initiateShareFlow(currentInviterToken, "WechatSession", targetPackage = PACKAGE_WECHAT)
        }

        btnShareLine.setOnClickListener {
            initiateShareFlow(currentInviterToken, "Line", targetPackage = PACKAGE_LINE)
        }

        btnShareGeneric.setOnClickListener {
            // Hoja de compartición del sistema no segmentada; plataforma clasificada como Other
            initiateShareFlow(currentInviterToken, "Other", targetPackage = null)
        }
    }

    /**
     * Ayudante para verificar si la aplicación social de destino está instalada antes de reportar la telemetría de un canal específico.
     * Requiere la declaración <queries> en AndroidManifest.xml en Android 11+ (API 30+).
     */
    private fun isAppInstalled(packageName: String?): Boolean {
        if (packageName.isNullOrEmpty()) return false
        return try {
            packageManager.getPackageInfo(packageName, PackageManager.GET_ACTIVITIES)
            true
        } catch (e: PackageManager.NameNotFoundException) {
            false
        } catch (e: Exception) {
            Log.w(TAG, "Excepción de inspección de paquete para $packageName: ${e.message}")
            false
        }
    }

    /**
     * Copia la URL completa de invitación al portapapeles del sistema como respaldo final.
     */
    private fun copyInviteLinkToClipboard(shareUri: String): Boolean {
        return try {
            val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
            clipboard.setPrimaryClip(ClipData.newPlainText("Enlace de invitación de referido", shareUri))
            true
        } catch (e: Exception) {
            Log.e(TAG, "Error al copiar el enlace de invitación: ${e.message}", e)
            false
        }
    }

    private fun showShareFailureFallback(shareUri: String) {
        val copied = copyInviteLinkToClipboard(shareUri)
        val message = if (copied) {
            "No se pudo abrir la aplicación para compartir. Enlace de invitación copiado al portapapeles."
        } else {
            "No se pudo abrir la aplicación para compartir ni copiar el enlace de invitación."
        }
        Toast.makeText(this, message, Toast.LENGTH_LONG).show()
    }

    /**
     * Registra la intención de compartir a través de la telemetría propiedad de la aplicación con un respaldo de tiempo de espera no bloqueante.
     *
     * @param shareCode Token opaco del invitador (estrictamente <= 128 caracteres)
     * @param platformIdentifier Canal social de destino que coincide con la taxonomía de informes
     * @param targetPackage Nombre específico del paquete de la aplicación, o nulo para el selector de sistema genérico
     */
    private fun initiateShareFlow(shareCode: String, platformIdentifier: String, targetPackage: String?) {
        // Aplicar verificación antirrebote
        if (!isSharingInProgress.compareAndSet(false, true)) {
            Log.d(TAG, "Invocación de compartición ya en curso. Ignorando clic duplicado.")
            return
        }

        val isTargetInstalled = isAppInstalled(targetPackage)
        val effectivePlatform = if (isTargetInstalled) platformIdentifier else "Other"
        val effectivePackage = if (isTargetInstalled) targetPackage else null

        val isDispatched = AtomicBoolean(false)
        val mainHandler = Handler(Looper.getMainLooper())

        // Ejecutable de tiempo de espera no bloqueante: Garantiza que la hoja de compartición de la interfaz de usuario se abra incluso si el protocolo de enlace de red se retrasa
        val timeoutRunnable = Runnable {
            if (isDispatched.compareAndSet(false, true)) {
                Log.w(TAG, "Los informes previos a la compartición agotaron el tiempo de espera después de ${SHARE_TIMEOUT_MS}ms. Continuando con el envío.")
                dispatchShareSafely(shareCode, effectivePlatform, effectivePackage)
            }
        }
        mainHandler.postDelayed(timeoutRunnable, SHARE_TIMEOUT_MS)

        // Reportar de forma asincrónica la intención de compartición a través del adaptador de telemetría propiedad de la aplicación
        shareTelemetry.reportIntent(shareCode, effectivePlatform) { result ->
            mainHandler.removeCallbacks(timeoutRunnable)
            if (isDispatched.compareAndSet(false, true)) {
                if (result.isFailure) {
                    Log.w(TAG, "La telemetría de compartición falló: ${result.exceptionOrNull()?.message}")
                } else {
                    Log.d(TAG, "Intención de compartición registrada para $effectivePlatform")
                }
                mainHandler.post {
                    dispatchShareSafely(shareCode, effectivePlatform, effectivePackage)
                }
            }
        }
    }

    /**
     * Ejecuta el envío de la intención con verificación del ciclo de vida y restablecimiento de estado garantizado en el bloque finally.
     */
    private fun dispatchShareSafely(shareCode: String, platform: String, targetPackage: String?) {
        try {
            if (isFinishing || isDestroyed) {
                Log.d(TAG, "Actividad finalizada o destruida; omitiendo el envío de compartición.")
                return
            }
            dispatchShareAction(shareCode, platform, targetPackage)
        } catch (e: Exception) {
            Log.e(TAG, "El envío de compartición encontró una excepción no controlada: ${e.message}", e)
        } finally {
            isSharingInProgress.set(false)
        }
    }

    private fun dispatchShareAction(shareCode: String, platform: String, targetPackage: String?) {
        // Construir la URL de destino de forma segura usando Uri.Builder para aplicar la codificación RFC 3986
        val shareUri = Uri.Builder()
            .scheme("https")
            .authority(BASE_INVITE_HOST)
            .appendEncodedPath(BASE_INVITE_PATH)
            .appendQueryParameter("shareCode", shareCode)
            .appendQueryParameter("platform", platform)
            .build()
            .toString()

        val shareMessage = "¡Únete a mí en la aplicación y obtén un cupón de bienvenida! Descárgala aquí: $shareUri"

        val sendIntent = Intent(Intent.ACTION_SEND).apply {
            putExtra(Intent.EXTRA_TEXT, shareMessage)
            type = "text/plain"
        }

        if (targetPackage != null) {
            sendIntent.setPackage(targetPackage)
            try {
                startActivity(sendIntent)
                return
            } catch (e: Exception) {
                Log.w(TAG, "El lanzamiento de la app de destino falló: ${e.message}", e)
            }
        }

        // Usar el selector de compartición del sistema cuando la aplicación de destino no esté disponible o el lanzamiento de la compartición dirigida haya fallado
        try {
            sendIntent.setPackage(null)
            val fallbackChooser = Intent.createChooser(sendIntent, "Invitar amigos a través de:")
            startActivity(fallbackChooser)
        } catch (e: Exception) {
            Log.e(TAG, "El selector de compartición del sistema falló: ${e.message}", e)
            showShareFailureFallback(shareUri)
        }
    }
}

// Interfaz de servicio de telemetría propiedad de la aplicación ilustrativa
class ShareTelemetryService {
    fun reportIntent(shareCode: String, platform: String, callback: (Result<Unit>) -> Unit) {
        // Implementación: enviar solicitud de red al backend de telemetría de la aplicación
        callback(Result.success(Unit))
    }
}

Para registrar un perfil de aplicación y recuperar las claves de configuración necesarias para el seguimiento de comparticiones, los equipos pueden acceder a la consola de desarrolladores de OpoInstall.

Paso 2: Configuración del SDK de Web JS para Capturar Parámetros de Compartición Dinámicos

Integración del SDK Web a Través de un Adaptador Verificado por Versión

La implementación de la página de destino a continuación es un patrón de integración ilustrativo, no una integración verificada del SDK de OpoInstall directo. Antes de la implementación, confirme la URL exacta del paquete de JavaScript, la firma de inicialización, la devolución de llamada de preparación (readiness callback), el método de activación o instalación y el esquema de parámetros con la documentación oficial para la versión del SDK que se está implementando.

Mantenga el comportamiento específico del SDK detrás de un pequeño adaptador de aplicación. El adaptador debe exponer un resultado de inicialización documentado y una sola operación de activación o instalación a la página de destino. Mapee estas operaciones a la API del proveedor real solo después de verificar los nombres de los métodos correspondientes, el comportamiento de devolución de llamada y los requisitos de configuración.

La página de destino debe continuar validando el shareCode entrante, preservar los parámetros de referidos en las rutas de respaldo aprobadas y evitar la navegación duplicada. Si el SDK no se inicializa o su punto de entrada documentado no está disponible, utilice la ruta de respaldo configurada. No afirme que el respaldo puede recuperar la atribución diferida a menos que se hayan probado la integración del backend y de la plataforma para admitirla.

Automatización de la Extracción de Cadena de Consulta shareCode a Través de URLSearchParams del Navegador

Cuando se construyen las URL de compartición, la aplicación adjunta el token del invitador como un parámetro de consulta (por ejemplo, https://promo.example.com/invite.html?shareCode=usr_9f82a1b4&platform=WechatSession).

En la página de destino, los scripts del lado del cliente extraen este valor utilizando interfaces estándar del navegador como URLSearchParams. Para defenderse contra entradas maliciosas o secuencias de comandos en sitios cruzados (XSS), el script debe validar el token frente a una lista de permitidos y un patrón de formato antes de inicializar el SDK:

const query = new URLSearchParams(window.location.search);
const rawShareCode = query.get("shareCode");
const safePattern = /^[A-Za-z0-9_-]{1,128}$/;
const sanitizedShareCode = (rawShareCode && safePattern.test(rawShareCode)) ? rawShareCode : "";

Preparación del Contexto de Referido en Memoria Efímera y Búferes del Sistema

Cuando el SDK de Web JS se inicializa, ingiere el shareCode sanitizado junto con cualquier identificador de campaña suplementario (channelCode). Cuando el usuario hace clic en el botón principal de llamada a la acción (CTA), el SDK coordina la preparación del contexto:

• Registro en el Servidor de Atribución: El script transmite una solicitud de red asincrónica que vincula la sesión web actual y el contexto del cliente al shareCode.
• Preparación en el Portapapeles del Sistema: El acceso al portapapeles está sujeto a los permisos del navegador, los requisitos de activación del usuario y las políticas de seguridad específicas de la implementación. Las implementaciones web deben tratar la preparación del portapapeles como una mejora opcional y proporcionar un respaldo cuando el acceso sea denegado o no esté disponible.
• Coordinación de Respaldo: Si el acceso al portapapeles está restringido, denegado por el aviso del usuario o borrado por acciones posteriores del usuario, la arquitectura de atribución recurre a la coincidencia de sesiones del lado del servidor o a canales de referente de instalación compatibles con la plataforma.

Vinculación del Botón de CTA de Descarga para Ejecutar el Registro de Parámetros Diferidos

La página de destino vincula su botón de descarga principal directamente al método de ejecución del SDK (wakeupOrInstall()).

El SDK de Web JS gestiona internamente el ciclo de vida de redirección: inicia un intento de activación de la aplicación a través de esquemas configurados o Enlaces Universales, y si la aplicación no está instalada, ejecuta una redirección retrasada a la tienda de aplicaciones configurada. El código de usuario debe depender de la gestión de navegación interna del SDK durante la ejecución normal, reservando la navegación de respaldo directa para escenarios donde el script del SDK no se carga, genera una excepción sincrónica o está bloqueado por los controles de seguridad del navegador.

El patrón de implementación a continuación demuestra cómo integrar el SDK de Web JS para capturar los parámetros de consulta shareCode entrantes, detectar contenedores sociales integrados en la aplicación, gestionar el estado de la cola de clics y preservar los parámetros a través de rutas de respaldo sin claves duplicadas o fragmentos de URI mal formados:

<!-- Ingestión y Enrutamiento de Parámetros de Compartición Dinámicos del SDK de Web JS -->
<!-- Archivo: /var/www/html/invite.html -->
<!--
NOTA DE INTEGRACIÓN:
Este ejemplo requiere un adaptador verificado con la versión del SDK implementada.
No asuma que el constructor, la ruta CDN, la devolución de llamada o los nombres de los métodos mostrados
en un fragmento ilustrativo coinciden con el SDK del proveedor actual.
-->
<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Acepta tu Invitación de Referido</title>
    <!-- Incluir el SDK de Web JS de OpoInstall verificado desde el CDN oficial -->
    <script src="https://web.cdn.opoinstallcloud.com/opoinstall.js"></script>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
            margin: 0;
            padding: 20px;
            text-align: center;
            background-color: #f8fafc;
        }
        .card {
            background: #ffffff;
            border-radius: 12px;
            padding: 32px 24px;
            max-width: 420px;
            margin: 40px auto;
            box-shadow: 0 4px 6px -1px rgba(0,0,0,0.1);
        }
        button {
            background-color: #2563eb;
            color: #ffffff;
            border: none;
            padding: 14px 28px;
            font-size: 16px;
            font-weight: 600;
            border-radius: 8px;
            cursor: pointer;
            width: 100%;
            margin-top: 20px;
        }
        button:disabled {
            background-color: #94a3b8;
            cursor: not-allowed;
        }
        /* Superposición de guía visual para contenedores webview restringidos dentro de la app */
        .webview-guide-mask {
            display: none;
            position: fixed;
            top: 0;
            left: 0;
            width: 100%;
            height: 100%;
            background: rgba(0, 0, 0, 0.85);
            color: #ffffff;
            z-index: 9999;
            padding-top: 40px;
            box-sizing: border-box;
        }
        .guide-arrow {
            font-size: 32px;
            text-align: right;
            padding-right: 30px;
        }
        .guide-text {
            font-size: 18px;
            line-height: 1.6;
            margin-top: 20px;
            padding: 0 30px;
        }
    </style>
</head>
<body>
    <main class="card">
        <h1>Bienvenido a la App</h1>
        <p id="invite-desc">Tu amigo te ha invitado a unirte. Toca abajo para instalar y reclamar tu crédito de bienvenida.</p>
        
        <!-- Botón de conversión principal -->
        <button id="btn-install" type="button">Descargar y Reclamar Bono</button>
        
        <!-- Ejemplo de punto de finalización de redirección propiedad de la aplicación; reemplazar con una ruta HTTPS implementada -->
        <p style="margin-top: 16px; font-size: 14px;">
            <a id="fallback-store-link" href="https://promo.example.com/app-redirect">Enlace Directo a la Tienda</a>
        </p>
    </main>

    <!-- Aviso superpuesto mostrado dentro de webviews de mensajería restringidos (WeChat, Line) -->
    <div id="webview-guide" class="webview-guide-mask">
        <div class="guide-arrow">↗</div>
        <div class="guide-text">
            Toca el menú en la esquina superior derecha (•••) y selecciona <strong>"Abrir en el Navegador"</strong> (Safari / Chrome) para descargar la aplicación.
        </div>
    </div>

    <script>
    /**
     * Extrae y sanea el parámetro de consulta shareCode de window.location.
     * Aplica límites alfanuméricos seguros para URL de hasta 128 caracteres según la especificación.
     */
    function getSanitizedShareCode() {
        try {
            const query = new URLSearchParams(window.location.search);
            const rawCode = query.get("shareCode");
            const pattern = /^[A-Za-z0-9_-]{1,128}$/;
            return (rawCode && pattern.test(rawCode)) ? rawCode : "";
        } catch (e) {
            console.error("Error al analizar los parámetros de búsqueda:", e);
            return "";
        }
    }

    /**
     * Extrae y sanea el parámetro de consulta de la plataforma.
     */
    function getSanitizedPlatform() {
        try {
            const query = new URLSearchParams(window.location.search);
            const rawPlatform = query.get("platform");
            const pattern = /^[A-Za-z0-9_]{1,32}$/;
            return (rawPlatform && pattern.test(rawPlatform)) ? rawPlatform : "";
        } catch (e) {
            return "";
        }
    }

    /**
     * Detecta contenedores de navegadores integrados restringidos (WeChat, Line, WhatsApp, Facebook).
     */
    function detectInAppBrowser() {
        const ua = navigator.userAgent.toLowerCase();
        return {
            isWeChat: ua.indexOf("micromessenger") !== -1,
            isLine: ua.indexOf("line/") !== -1,
            isWhatsApp: ua.indexOf("whatsapp") !== -1,
            isFacebook: ua.indexOf("fbav") !== -1 || ua.indexOf("instagram") !== -1
        };
    }

    /**
     * Decodifica de forma segura un componente de URI, recurriendo a la cadena sin procesar en caso de codificación porcentual mal formada.
     */
    function safeDecode(str) {
        if (!str) return "";
        try {
            return decodeURIComponent(str.replace(/\+/g, " "));
        } catch (e) {
            return str;
        }
    }

    /**
     * Ejecuta la navegación de respaldo, reemplazando o actualizando el parámetro shareCode
     * a través del análisis de URL y rutas de respaldo de cadenas sin corromper los fragmentos de URL.
     */
    function executeFallbackNavigation(fallbackLink, shareCode, platform) {
        if (!fallbackLink || !fallbackLink.href) {
            console.error("El enlace de destino de respaldo no está definido.");
            return;
        }

        let destinationUrl = fallbackLink.href;
        try {
            const url = new URL(destinationUrl, window.location.origin);
            if (shareCode) {
                url.searchParams.set("shareCode", shareCode);
            }
            if (platform) {
                url.searchParams.set("platform", platform);
            }
            destinationUrl = url.toString();
        } catch (err) {
            console.warn("El análisis de la API de URL falló, aplicando respaldo de cadena robusto:", err);
            const hashIndex = destinationUrl.indexOf("#");
            const fragment = hashIndex !== -1 ? destinationUrl.substring(hashIndex) : "";
            const rawBase = hashIndex !== -1 ? destinationUrl.substring(0, hashIndex) : destinationUrl;

            const qIndex = rawBase.indexOf("?");
            const pathname = qIndex !== -1 ? rawBase.substring(0, qIndex) : rawBase;
            const queryString = qIndex !== -1 ? rawBase.substring(qIndex + 1) : "";

            const params = {};
            if (queryString) {
                const pairs = queryString.split("&");
                for (let i = 0; i < pairs.length; i++) {
                    if (!pairs[i]) continue;
                    const parts = pairs[i].split("=");
                    const key = safeDecode(parts[0]);
                    const value = parts.length > 1 ? safeDecode(parts.slice(1).join("=")) : "";
                    if (key) {
                        params[key] = value;
                    }
                }
            }

            if (shareCode) params["shareCode"] = shareCode;
            if (platform) params["platform"] = platform;

            const serializedPairs = [];
            for (const k in params) {
                if (Object.prototype.hasOwnProperty.call(params, k)) {
                    serializedPairs.push(encodeURIComponent(k) + "=" + encodeURIComponent(params[k]));
                }
            }

            const newQuery = serializedPairs.length > 0 ? "?" + serializedPairs.join("&") : "";
            destinationUrl = pathname + newQuery + fragment;
        }

        window.location.href = destinationUrl;
    }

    document.addEventListener("DOMContentLoaded", function() {
        const shareCode = getSanitizedShareCode();
        const platform = getSanitizedPlatform();
        const inApp = detectInAppBrowser();
        const installBtn = document.getElementById("btn-install");
        const guideOverlay = document.getElementById("webview-guide");
        const fallbackLink = document.getElementById("fallback-store-link");

        // Mostrar máscara de guía visual si se abre en contenedores restringidos que interceptan descargas
        if (inApp.isWeChat || inApp.isLine) {
            if (guideOverlay) guideOverlay.style.display = "block";
        }

        // Actualizar inmediatamente el href del enlace de respaldo estático al cargar el DOM para que los clics directos preserven los parámetros
        if (fallbackLink && fallbackLink.href) {
            try {
                const initialUrl = new URL(fallbackLink.href, window.location.origin);
                if (shareCode) initialUrl.searchParams.set("shareCode", shareCode);
                if (platform) initialUrl.searchParams.set("platform", platform);
                fallbackLink.href = initialUrl.toString();
            } catch (e) {
                // Análisis de respaldo manejado en el momento del clic
            }
        }

        // Empaquetar parámetros dinámicos para la ingestión de OpoInstall
        const dynamicData = {
            shareCode: shareCode,
            platform: platform
        };

        // Preparación del SDK y estado de acción única
        let isSdkReady = false;
        let isSdkBlocked = false;
        let isClickQueued = false;
        let actionStarted = false;
        let installerInstance = null;
        let clickTimeoutId = null;

        // Umbral de respaldo de inicialización definido por la aplicación, no un valor predeterminado verificado del proveedor
        const SDK_CLICK_TIMEOUT_MS = 1500;

        function clearClickTimeout() {
            if (clickTimeoutId !== null) {
                clearTimeout(clickTimeoutId);
                clickTimeoutId = null;
            }
        }

        function restoreInstallButton() {
            if (!installBtn) return;
            installBtn.disabled = false;
            installBtn.textContent = "Descargar y Reclamar Bono";
        }

        function triggerSdkWakeup() {
            try {
                if (installerInstance && typeof installerInstance.wakeupOrInstall === "function") {
                    installerInstance.wakeupOrInstall({
                        data: dynamicData,
                        channelCode: "viral_social_share"
                    });
                } else {
                    executeFallbackNavigation(fallbackLink, shareCode, platform);
                }
            } catch (err) {
                console.error("La activación del SDK falló:", err);
                executeFallbackNavigation(fallbackLink, shareCode, platform);
            }
        }

        // Todas las rutas de navegación deben pasar por este protector de disparo único
        function runOnce(action) {
            if (actionStarted) return;
            actionStarted = true;
            isClickQueued = false;
            clearClickTimeout();

            if (installBtn) {
                installBtn.disabled = true;
                installBtn.textContent = "Abriendo...";
            }

            action();
        }

        function handleInstallClick() {
            if (actionStarted) return;

            if (isSdkReady) {
                runOnce(triggerSdkWakeup);
                return;
            }

            if (isSdkBlocked) {
                runOnce(function() {
                    executeFallbackNavigation(fallbackLink, shareCode, platform);
                });
                return;
            }

            // Encolar el clic mientras se inicializa el SDK
            isClickQueued = true;
            if (installBtn) {
                installBtn.disabled = true;
                installBtn.textContent = "Conectando con la App Store...";
            }

            clearClickTimeout();

            clickTimeoutId = setTimeout(function() {
                if (actionStarted || isSdkReady || !isClickQueued) {
                    return;
                }
                isSdkBlocked = true;
                runOnce(function() {
                    executeFallbackNavigation(fallbackLink, shareCode, platform);
                });
            }, SDK_CLICK_TIMEOUT_MS);
        }

        if (installBtn) {
            installBtn.addEventListener("click", handleInstallClick);
        }

        // Inicializar el SDK de Web JS
        if (typeof OpoInstall === "function") {
            try {
                // Reemplazar con la clave de aplicación obtenida de la consola del proveedor configurada;
                // nunca envíe secretos de producción al control de código fuente público.
                installerInstance = new OpoInstall({
                    appKey: "OPOINSTALL_APPKEY_PLACEHOLDER",
                    onready: function() {
                        if (this && typeof this.wakeupOrInstall === "function") {
                            installerInstance = this;
                        }

                        isSdkReady = true;
                        clearClickTimeout();

                        // Una devolución de llamada tardía nunca debe repetir una acción completada
                        if (actionStarted) return;

                        if (isClickQueued) {
                            runOnce(triggerSdkWakeup);
                        } else {
                            restoreInstallButton();
                        }
                    }
                });
            } catch (err) {
                console.error("La inicialización de OpoInstall falló:", err);
                isSdkBlocked = true;
                clearClickTimeout();

                if (isClickQueued) {
                    runOnce(function() {
                        executeFallbackNavigation(fallbackLink, shareCode, platform);
                    });
                } else {
                    restoreInstallButton();
                }
            }
        } else {
            console.warn("SDK de OpoInstall no disponible; navegación de respaldo habilitada.");
            isSdkBlocked = true;
            restoreInstallButton();
        }
    });
    </script>
</body>
</html>

Paso 3: Recuperación de Parámetros de Referidos y Vinculación de Cuentas

Recuperación del Contexto de Referidos Durante el Lanzamiento Inicial de la App

Después de la instalación, la aplicación debe intentar recuperar el contexto del referido utilizando el mecanismo compatible con la plataforma y el SDK de atribución implementado.

No asuma que un parámetro presente en la URL de la página de destino web sobrevivirá automáticamente a una instalación en la tienda de aplicaciones.

En Android, la aplicación puede usar Google Play Install Referrer cuando la ruta de instalación y la carga útil del referente configurado lo admiten. Si un SDK de atribución de terceros proporciona una API de recuperación adicional, verifique su firma de método, el comportamiento de devolución de llamada y el esquema de carga útil con la versión exacta del SDK en uso.

En iOS, el manejo directo de Enlaces Universales y la recuperación de referidos posterior a la instalación deben tratarse como flujos separados. La aplicación debe utilizar un mecanismo documentado y permitido por la plataforma para la recuperación diferida. Si el mecanismo no se puede verificar o el contexto del referido no se puede recuperar, continúe con la incorporación sin atribuir la instalación a un invitador.

Recuperación No Bloqueante y Comportamiento de Reintento

La recuperación de referidos no debe bloquear el hilo principal de la interfaz de usuario ni impedir que el usuario complete el registro. Trate la operación de recuperación como asincrónica, aplique un tiempo de espera adecuado para el servicio de la aplicación o SDK real y registre un resultado distintivo para una recuperación exitosa, resultados vacíos, tiempo de espera (timeout) y fallos.

Configure el tiempo de espera de acuerdo con el comportamiento documentado del SDK y los requisitos de incorporación de la aplicación. Cualquier valor de tiempo de espera que se muestre en este ejemplo es una configuración a nivel de aplicación, no un valor predeterminado del proveedor a menos que la documentación relevante del SDK lo confirme explícitamente.

Se puede intentar un reintento cuando la API documentada lo admita y la aplicación tenga una política de reintentos definida. Evite las solicitudes de vinculación de cuentas duplicadas y evite emitir recompensas repetidamente cuando llegue una devolución de llamada retrasada después de que se haya completado el registro.

Validación de Referidos en el Lado del Servidor

Trate todos los valores de referidos reportados por el cliente como entradas no confiables. El backend de la aplicación debe validar el token del invitador candidato, verificar la elegibilidad del invitado y aplicar las reglas comerciales del programa de referidos antes de crear la vinculación.

Utilice una restricción de unicidad a nivel de base de datos o un control transaccional equivalente para evitar múltiples vinculaciones de invitadores para el mismo invitado. Mantenga la vinculación de referidos separada de la emisión de recompensas, y libere las recompensas solo después de que se haya verificado el hito de activación requerido en el servidor.

Gestión de Restricciones del Navegador Integrado en WeChat, Line y WhatsApp

La Barrera del Sandbox del Contenedor: Cómo las Aplicaciones de Mensajería Interceptan Esquemas Personalizados y Descargas Directas de APK

La gran mayoría de las comparticiones de referidos virales ocurren dentro de aplicaciones de mensajería móvil. Sin embargo, plataformas como WeChat, Line y WhatsApp renderizan enlaces web externos dentro de webviews integradas en sandboxes que frecuentemente interceptan, restringen o modifican descargas binarias directas y esquemas de enlaces profundos dependiendo de la versión del sistema operativo y las políticas de seguridad del contenedor.

Cuando un usuario invitado toca un enlace de referido dentro de un navegador integrado en la app:

• Las Descargas Directas de APK son Interceptadas: En Android, los intentos de descargar archivos binarios .apk directamente desde la página de destino web son interceptados o bloqueados frecuentemente por el contenedor webview.
Los Esquemas de URL Personalizados están Bloqueados: Las invocaciones de esquemas de URL privados (myapp://invite?code=123) a menudo fallan al ejecutarse, impidiendo lanzamientos directos de aplicaciones nativas para usuarios que ya tienen la aplicación instalada.
Los Enlaces Universales pueden ser Suprimidos: Ciertas aplicaciones de mensajería interceptan la navegación saliente, evitando que los Enlaces Universales estándar de iOS se resuelvan hacia el exterior del sistema operativo.

Detección de Cabeceras de Agente de Usuario (User-Agent) Integradas en la App

Para manejar estas limitaciones del contenedor sin problemas, la página de destino para compartir debe inspeccionar la cadena User-Agent del navegador entrante durante la carga inicial del DOM:

• Detección de WeChat: Inspeccionando navigator.userAgent para MicroMessenger.
• Detección de Line: Inspeccionando navigator.userAgent para Line/.
• Detección de WhatsApp: Inspeccionando navigator.userAgent para WhatsApp.
• Facebook / Messenger / Instagram: Inspeccionando navigator.userAgent para FBAV o Instagram.

Evaluación de Tácticas de Redirección: Transferencia Directa de la App vs. Transición al Navegador del Sistema

Los sistemas operativos y las aplicaciones sociales exhiben comportamientos de navegación distintos:

• Entornos de WeChat y Line: Estos contenedores restringen las descargas binarias directas y la ejecución de esquemas externos. Intentar una redirección automática a menudo activa pantallas de advertencia de la plataforma. La página de destino muestra una guía visual explícita que insta al usuario a abrir el enlace en el navegador predeterminado del sistema del dispositivo (Safari en iOS, Chrome en Android).
Entorno de WhatsApp: En implementaciones modernas de iOS y Android, WhatsApp normalmente abre enlaces web en viewports integrados proporcionados por el sistema (como SFSafariViewController en iOS o Chrome Custom Tabs en Android). Estos entornos permiten la navegación web estándar y admiten transiciones a las tiendas de aplicaciones de la plataforma, aunque los esquemas de URL personalizados aún pueden requerir un toque explícito del usuario.

Implementación de Guía de Usuario Elegida: Superposición de Avisos de Menús Nativos cuando la Redirección Directa Falla

Cuando un webview integrado en la app previene transferencias externas programáticas, las páginas de destino despliegan una guía visual para el usuario:

• Superposiciones de Máscaras Condicionales: Cuando se detecta MicroMessenger o Line/, muestra una superposición visual de alto contraste que apunta hacia la esquina superior derecha de la pantalla.
• Copia de Acción Explícita: El aviso instruye al usuario: “Toca el menú en la esquina superior derecha (•••) y selecciona ‘Abrir en el Navegador’ (Safari / Chrome) para descargar la aplicación.”
• Preservación del Estado de los Parámetros: Si el usuario realiza la transición a un navegador externo cargando la misma URL, los parámetros de consulta (?shareCode=...) permanecen intactos en la barra de direcciones, siempre que las redirecciones intermedias no los eliminen. Cuando la página de destino se vuelve a cargar en Safari o Chrome, el SDK de Web JS se ejecuta limpiamente y prepara el contexto del referido.

Solución de Problemas de Caídas de Parámetros de Referidos a Través de Embudos Sociales

Diagnóstico de la Eliminación de Parámetros a Través de Proxies Agresivos de Acortamiento de Enlaces en la App

Ciertas plataformas sociales enrutan los enlaces externos compartidos a través de dominios intermediarios de envoltura o acortamiento de enlaces (por ejemplo, l.facebook.com de Facebook o t.co de Twitter). En algunos casos, estos saltos de redirección eliminan parámetros de consulta no estándar o agregan identificadores de clics internos conflictivos (fbclid).

Para evitar la pérdida de parámetros en redirecciones sociales de múltiples saltos:

• Nomenclatura de Parámetros Estándar: Adhiérase a claves de consulta alfanuméricas estándar como shareCode y channelCode según el IETF RFC 3986.
• Validación de Enlaces Previa al Envío: Pruebe la resolución de enlaces en sesiones de chat en vivo en redes de mensajería de destino, inspeccionando window.location.search en la página de destino final para verificar que el parámetro shareCode sobreviva a todas las redirecciones intermedias.

Manejo de Comparticiones Web de Escritorio: Cuando los Usuarios Abren Enlaces de Referidos Móviles en Navegadores de PC

Si bien las campañas de referidos están diseñadas para dispositivos móviles, los usuarios frecuentemente abren enlaces de chat en computadoras de escritorio (por ejemplo, WhatsApp Web, WeChat para Mac/Windows o Slack). Si un usuario de escritorio accede a una página de destino de descarga móvil, las redirecciones de la tienda móvil fallan.

Las páginas de destino empresariales manejan el tráfico de escritorio a través de una degradación receptiva:

• Detección de Entorno de Escritorio: El SDK de Web JS detecta sistemas operativos de escritorio (Windows, macOS, Linux).
• Generación Dinámica de Códigos QR: En lugar de mostrar un botón de tienda móvil en el que no se puede hacer clic, las plantillas adaptables pueden mostrar condicionalmente un contenedor de código QR en viewports de escritorio.
• Escaneo multidispositivo: El usuario escanea el código QR de la pantalla de escritorio con su dispositivo móvil. El código QR codifica la URL de destino con el shareCode original, transfiriendo la sesión de referidos del escritorio al móvil.

Mitigación de Restricciones de Acceso al Portapapeles del Sistema Operativo

Los controles de privacidad del sistema operativo rigen el acceso al portapapeles:

• Reglas de Enfoque en Primer Plano de Android: Bajo Android 10 (nivel de API 29) y versiones posteriores, las aplicaciones en segundo plano no pueden leer los datos del portapapeles a través de Android ClipboardManager. El SDK nativo debe diferir la inspección del portapapeles hasta que la Actividad principal de la aplicación obtenga el foco activo de la ventana.
• Avisos de Portapapeles en iOS: En iOS 16 y versiones posteriores, el acceso programático a Apple UIPasteboard puede activar una notificación del sistema o un aviso pidiendo al usuario que permita pegar desde el navegador de origen.
Coordinación de Respaldo de Red: La arquitectura de atribución da cuenta de estas restricciones al tratar los búferes de portapapeles locales como una mejora oportunista, recurriendo a la coincidencia de sesiones del lado del servidor cuando las lecturas del portapapeles son denegadas o no están disponibles.

Protocolo de Verificación Previa al Envío para Embudos de Referidos Sociales en Dispositivos Físicos

Antes de lanzar una campaña de referidos para clientes, los equipos de ingeniería de crecimiento deben ejecutar la siguiente lista de verificación de validación sistemática:

• Respaldo de Compartición Dirigida en Android: Confirme que cuando WeChat o Line están desinstalados, la aplicación recurre elegantemente al selector de compartición del sistema.
• Respaldo de Copia de Enlace al Portapapeles en Android: Confirme que si el selector de compartición del sistema falla o genera una excepción, el enlace de referido completo se copia al portapapeles y se muestra una notificación emergente (toast).
• Retraso del SDK H5 y Navegación de Disparo Único: Simule un retraso de inicialización del SDK superior a 1500 ms para verificar que la navegación de respaldo se ejecute limpiamente y que los eventos onready tardíos no activen navegaciones duplicadas.
• Retención de Parámetros y Fragmentos H5: Pruebe la navegación de respaldo de la página de destino con URL que contengan parámetros de consulta existentes, claves duplicadas y #fragments para verificar un reemplazo limpio de los parámetros.
• Enlaces Universales de iOS y Transferencia a la Tienda: Pruebe la apertura directa de aplicaciones para usuarios existentes y evalúe la recuperación de parámetros posterior a la instalación frente a las reglas contra la toma de huellas digitales de Apple.
• Envío de Mensajería Social en Vivo: Envíe enlaces a sesiones de chat activas de WeChat y Line para verificar que las superposiciones de detección de navegadores integrados en la app guíen a los usuarios a Safari o Chrome sin omitir el shareCode.
• Vinculación de Backend e Idempotencia de Recompensas: Verifique que el backend de la aplicación acepte tokens candidatos, rechace vinculaciones duplicadas y mantenga las recompensas en un estado pendiente hasta que se completen los hitos verificados.

Análisis Comparativo de Arquitecturas de Seguimiento de Referidos

Comparación de Arquitecturas de Seguimiento de Referidos

Compromisos (Trade-offs) en Complejidad de Implementación, Fricción de Conversión y Precisión de Atribución

Los códigos promocionales manuales son comparativamente sencillos de implementar, pero requieren que los usuarios ingresen y canjeen un código. Esto puede introducir fricción y crea oportunidades para compartir códigos fuera de la relación de referidos prevista.

El fingerprinting del dispositivo puede parecer que reduce la interacción del usuario, pero su fiabilidad depende de la implementación de la coincidencia y de las señales disponibles. No debe utilizarse cuando entra en conflicto con los requisitos de privacidad aplicables, incluidas las restricciones de Apple sobre el fingerprinting prohibido.

Los parámetros de referidos explícitos proporcionan una representación clara a nivel de negocio del invitador previsto. Sin embargo, llevar un token en una URL web no equivale a recuperar ese token después de una instalación en la tienda de aplicaciones. La solución general debe combinar la continuidad de los parámetros, un mecanismo de recuperación compatible con la plataforma y la validación del lado del servidor. Cuando la instalación falla en la recuperación, debe permanecer como no atribuida en lugar de asignarse a un invitador no verificado.

Resumen y Marco de Decisiones

El seguimiento automatizado de referidos móviles puede reducir la entrada manual de códigos de referencia al llevar un token de invitador explícito a través de un flujo de compartición web y validar la relación de referidos resultante en el backend de la aplicación.

Una implementación confiable requiere algo más que agregar un parámetro de consulta shareCode. La página de destino debe preservar el token a través de redirecciones compatibles, la aplicación debe utilizar un mecanismo de recuperación verificado para la plataforma relevante, y el backend debe validar la elegibilidad de la cuenta y hacer cumplir la vinculación idempotente y la emisión de recompensas.

Android e iOS deben evaluarse por separado. Google Play Install Referrer puede proporcionar metadatos de instalación compatibles en Android. En iOS, los Enlaces Universales admiten el enrutamiento directo cuando la aplicación está instalada, pero no garantizan automáticamente la recuperación de parámetros diferidos después de una instalación desde la App Store. Cualquier mecanismo de recuperación adicional debe documentarse, probarse y revisarse frente a los requisitos de privacidad de la plataforma aplicables.

Para la implementación en producción, verifique todos los nombres de los métodos del SDK, los valores de configuración, los identificadores de canales y los esquemas de devolución de llamada con la versión exacta que se está integrando. Pruebe el recorrido completo en dispositivos limpios y en las aplicaciones de mensajería de destino. Cuando un referido no se pueda recuperar a través de un mecanismo compatible, permita que la incorporación continúe y registre el resultado como no atribuido en lugar de crear una relación de referido no verificada.

Los SDKs y la documentación para desarrolladores de OpoInstall pueden proporcionar componentes para implementar esta arquitectura. Confirme las capacidades específicas y el comportamiento de la plataforma admitidos por la versión implementada antes de confiar en ellos en una campaña de referidos en producción.

Para obtener detalles de integración, consulte la documentación para desarrolladores de OpoInstall, el centro de descargas del SDK de OpoInstall y la consola de desarrolladores de OpoInstall. Utilice la documentación oficial correspondiente de la plataforma Android y Apple para validar el comportamiento de instalación y privacidad relevante para la aplicación.

Materiales Relacionados

• Conceptos: Seguimiento Automatizado de Referidos, Vinculación de Invitador a Invitado, Enlaces Profundos Diferidos, Sandboxing de Webview en la App

• Tecnologías: SDK de Atribución Móvil, SDK de Web JS, Enlaces Universales, Enlaces de Aplicaciones de Android (Android App Links), Postbacks S2S

• Estándares: Sintaxis Genérica de Identificador de Recurso Uniforme (URI) IETF RFC 3986, Especificación de API de Portapapeles y Eventos W3C

• Interfaces de Integración: Telemetría de intención de compartición propiedad de la aplicación, la API de atribución o referente de instalación documentada para la versión del SDK implementada, enrutamiento de enlaces profundos específico de la plataforma y validación de referidos del lado del servidor.

• Documentación Oficial y Referencias:

  • Guía de Privacidad del Usuario y Uso de Datos de Apple

  • Documentación de la API Google Play Install Referrer

  • Guía para Desarrolladores de Android de Google sobre Visibilidad de Paquetes en Android 11

  • Guía para Desarrolladores de Android de Google sobre ClipboardManager y Requisitos de Enfoque

  • Directrices y Riesgos de Seguridad del Top 10 Móvil de OWASP