Guía de instalación para desarrolladores

Aprenda a instalar, configurar y utilizar Appcues en su pila tecnológica.

Updated at August 1st, 2025

Home
Instalación y desarrolladores
Experiencias web
Experiencias móviles
Flujos de trabajo
Análisis y datos
Gestión de cuentas
Mejores prácticas
Integraciones

Guía técnica completa para la instalación web directa

Nuestra guía completa para instalar Appcues directamente en su producto. Esta guía técnica cubrirá el proceso de principio a fin y destacará los componentes necesarios y opcionales necesarios para lograr una implementación eficaz y exitosa con Appcues .

La instalación requiere una hora o más de trabajo por parte de un desarrollador con conocimientos sobre cómo su producto rastrea las propiedades y eventos del usuario. Necesitará acceso a la cuenta de Appcues de su equipo para completar la instalación.

¿Buscas una descripción general sin tecnicismos? ¡Consúltala aquí !
¿Le interesan nuestras medidas de seguridad de datos? Consulte nuestro Centro de Confianza para obtener más información.

Esta guía se centra en la instalación directa Appcues en aplicaciones web. Para obtener información sobre otros métodos de instalación, consulte las guías a continuación:

¿Quieres instalarlo en una aplicación móvil? ¡Consulta la guía del SDK móvil !

Antes de empezar

Identifique quién en su equipo instalará Appcues
Complete un plan de instalación para delinear los componentes de instalación personalizados

¿Qué queremos decir con “instalar”?

Appcues funciona añadiendo un SDK a tu sitio web y JavaScript a tu aplicación. Appcues permite mostrar el contenido que creas a los usuarios en tus páginas. Este script se carga con la página y utiliza las propiedades de usuario y grupo, así como los eventos que envías, para determinar qué contenido deben ver los usuarios y cuándo. Una vez instalado Appcues , ¡puedes publicar contenido en tiempo real para tus usuarios!

Descripción general de los componentes de instalación

Hay algunos componentes clave que, en conjunto, contribuyen a una instalación exitosa Appcues . Si bien esta guía los abordará en detalle, a continuación se presenta una breve descripción de lo que constituye una instalación Appcues :

Agregue el script SDK Appcues a su producto : Appcues se agrega a su producto para conectarse a su cuenta Appcues y mostrar el contenido que ha creado.
Identificar usuarios y grupos : Informa Appcues cuando un usuario está presente y envía información sobre su identidad. Esto se utiliza para segmentar experiencias y crear segmentos.
Seguimiento de eventos : El seguimiento de eventos con Appcues le permite medir la interacción de sus usuarios con su producto. Estos eventos también pueden utilizarse para la segmentación y la segmentación.

Descripción general del video

¿Listo para instalar? ¡Sigue esta guía para los siguientes pasos!

Agregar el script SDK Appcues

El SDK Appcues se conecta a su cuenta Appcues y permite que funcione el Javascript Appcues .

Inserta el siguiente fragmento de código en el HTML <head></head> de tus páginas . Tu ID Appcues se encuentra en la página de configuración de Studio (también existe una versión copiable de este fragmento en la Guía de Studio ).

<script type="text/javascript">
  window.AppcuesSettings = { enableURLDetection: true };
</script>
<script src="//fast.appcues.com/YOUR_APPCUES_ID.js"></script>

Asegúrate de agregar el script en cada página donde quieras usar Appcues . Puedes hacerlo agregando el SDK a tu archivo index.html, a otro archivo raíz o a páginas específicas si quieres tener más control sobre en qué páginas se carga Appcues .

De forma predeterminada, el script enableURLDetection registra cualquier cambio en las páginas del producto donde se instalarán Appcues . Esto se utiliza para determinar la URL del usuario para una segmentación de flujo eficaz y experiencias entre páginas.

Una nota sobre el uso de TypeScript

Si usa Typescript y recibe un error 'does not exist' relacionado con Appcues , deberá asegurarse de que Appcues esté declarada como variable global. Una forma de hacerlo es con los siguientes fragmentos:

declare global {
  interface Window { Appcues: any; }
}
declare global {
  interface Window { AppcuesSettings: any; }
}

¿Se está instalando en una aplicación de página única ( SPA )? Quizás no desee incluir el script enableURLDetection . Consulte este documento para obtener más información.

¿Te interesa el SDK Appcues para tu dom ? ¡Consulta este documento !

Identificar usuarios y grupos

Appcues requiere que los usuarios se identifiquen para mostrar experiencias y rastrear eventos. Appcues solo utiliza los datos que envías explícitamente mediante las integraciones de identify(), group() y select.
Tenga en cuenta: Todos los usuarios únicos identificados por Appcues dentro de un período consecutivo de 30 días se consideran usuarios activos mensuales (MAU), independientemente de si ven una experiencia o no.

Ya sea que realice la instalación en nombre de alguien o trabaje directamente dentro de su equipo, lo alentamos a colaborar y seguir un Plan de instalación para delinear qué propiedades incluir.

¿Dónde se agregan identify() y group()?

Al agregar el SDK en el paso anterior, conecta su producto a su cuenta Appcues , pero aún necesita enviar datos a Appcues . Antes de agregar las llamadas de identificación y grupo, aquí se detalla dónde agregarlas en su código base:

¿A qué archivo agregarás las llamadas Appcues ? Puedes agregar Appcues directamente a un archivo existente o crear un archivo aparte para referenciarlo en tu código.
Para una identificación de usuario consistente, es mejor llamar a identify() al cargar la página (y posteriormente a cualquier llamada a group() si se utilizan datos de grupo)

Identificación de usuarios

Obligatorio : identificar usuarios individuales mediante Appcues .identify()

Componentes de identify()

ID de usuario único ( obligatorio )
- Appcues recomienda elegir IDs de usuario opacos y difíciles de adivinar, como un UUID. Consulta las Preguntas frecuentes para desarrolladores para obtener más información sobre cómo elegir un ID de usuario.
- En algunos casos, podríamos considerar el uso de un ID global. Si utilizamos nuestras integraciones, es posible que existan requisitos diferentes para el ID de usuario necesario para una integración exitosa. Encontrará más detalles al respecto en la sección "Otras consideraciones" .
Propiedades de usuario personalizadas/Atributos de usuario (opcional)
- Aunque técnicamente es opcional, le recomendamos encarecidamente que envíe datos adicionales a Appcues para ofrecer más opciones de segmentación para la experiencia del usuario. La falta de propiedades personalizadas limita considerablemente sus casos de uso Appcues .
- Las propiedades de usuario personalizadas variarán según los casos de uso y los datos disponibles, pero algunas propiedades comunes que vemos son CreatedAt, Rol, Correo electrónico e Idioma.
- Si no es fácil identificar a ese usuario con sus ID de usuario, puede configurar un identificador de visualización en Studio basado en una propiedad de usuario personalizada. Esto no afecta a su ID de usuario, ni es necesario que este valor sea único para cada usuario; recomendamos usar correo electrónico, nombre completo o una propiedad similar que su equipo pueda reconocer fácilmente.

Para conocer más formas de enviar propiedades de usuario personalizadas a Appcues , ¡consulte nuestras integraciones !

Ejemplo de llamada a la función identificar()

Este ejemplo utiliza información de usuario codificada (sin datos variables). Adáptelo para que refleje su ID de usuario y propiedades personalizadas antes de incluirlo en su código base.

window.Appcues.identify(
 “<<<USER_ID>>>”, // unique, required
  {
    // example custom user properties

    createdAt: 1566932390, // Unix timestamp of user signup date
    role: "Admin", // Current user's role or permissions
    firstName: "John", // current user's first name
    email: "john.doe@example.com", // Current user's email
    location: "90210", // for location-based targeting
    version: "2.0", // for version-based targeting
    language: "Spanish", // for multi-language applications
    }
);

Notas sobre la identificación de usuarios

Asegúrese de que la función identify() se llame antes de cualquier llamada Appcues .page() . Si no se implementa de esta manera, los usuarios finales podrían experimentar un retraso debido al almacenamiento en búfer de eventos mientras esperan a que se identifique a un usuario.
No envíe una propiedad personalizada llamada UserId , user_ID , etc. , ya que esto generará campos UserId duplicados en Appcues , lo que puede generar una segmentación confusa y engañosa. De forma predeterminada, el UserID único que aparece primero en su identify() se etiqueta como User Id en Appcues y la etiqueta no se puede cambiar.
Propiedades enviadas mediante integraciones : mientras que las propiedades identify() se envían en tiempo real al identificar al usuario, las propiedades de las integraciones se reciben mediante una sincronización y no se actualizan con cada identify() . Por ello, cualquier elemento inmediatamente relevante para el usuario debe enviarse directamente mediante identify() .
¿Quieres enviar datos de usuarios en masa? ¡Descubre la API Appcues !

Si necesita asegurarse de que solo los usuarios que verifique puedan enviar datos a Appcues y ver las experiencias Appcues dirigidas a ellos, considere configurar la Verificación de identidad .

Identificación de grupos

Recomendado : Identificar grupos de usuarios o cuentas mediante Appcues .group()

Componentes del grupo()

ID de grupo (obligatorio)
- El ID de grupo debe ser el valor único entre cada grupo o cuenta para distinguirlos. Puede ser un ID de cuenta, un nombre de cuenta, etc.
- Si utiliza nuestras integraciones para datos de grupo, es posible que haya requisitos diferentes en cuanto al ID de grupo para una integración exitosa. Más detalles al respecto en la sección "Otras consideraciones".
- Si bien las propiedades de grupo generalmente se utilizan con plataformas B2B para asociar usuarios finales dentro de una cuenta o empresa, las propiedades de grupo también se pueden usar para agrupar usuarios individuales en función de atributos compartidos (tipo de plan, etc.)
Propiedades de grupo personalizadas/Atributos de grupo
- Las mejores propiedades de grupo personalizadas son propiedades que se comparten entre usuarios dentro de ese grupo/cuenta y que no cambian de usuario a usuario dentro de la cuenta (los datos del usuario deben enviarse mediante identify() ).
- Si no es fácil identificar la cuenta con los ID de grupo, puede configurar un identificador de visualización en Studio basado en una propiedad de grupo personalizada. Esto no afecta a su ID de grupo, ni es necesario que este valor sea único para cada cuenta; recomendamos usar el nombre de la empresa, el nombre de la cuenta o una propiedad similar que su equipo pueda reconocer fácilmente.

Ejemplo de llamada al grupo()

Este ejemplo utiliza información de grupo predefinida (sin datos variables). Adáptelo para que refleje su ID de grupo y sus propiedades de grupo personalizadas antes de implementarlo en su código base.

window.Appcues.group(
 	"<<< GROUP_ID >>>", // unique, required
  	{
    	// example custom group properties

    	createdAt: 1566932390, // Unix timestamp of account signup date
    	purchasedAt: 1566932395, // Unix timestamp of account purchase date 
    	planTier: "Standard", // Account's plan tier
    	companyName: "CoolCo", // Account's name
    	MRR: 599, // Account's monthly recurring revenue
    	renewalDate: "06202035" // Timestamp of upcoming account renewal date
    	accountmanager: "Jerry" // Account manager
  	});

Notas sobre la identificación de grupos

Asegúrese de que se llame a identify() antes de group() , esto es para identificar correctamente al usuario y luego asignarlo al grupo.
Un usuario puede pertenecer a varios grupos , pero su actividad solo se asocia a un grupo a la vez. Solo el grupo asociado más recientemente con el usuario se considerará para la segmentación de las experiencias Appcues .
¿Quieres enviar datos grupales en masa? ¡Descubre la API Appcues !

Formatear datos de usuarios y grupos

Mantenga los nombres de las propiedades simples.
La interfaz de usuario Appcues intentará reformatear el nombre de la propiedad para que sea legible, por lo que una propiedad como "days_since_signup" se convierte en "Days Since Signup" y "planName" en "Plan Name". Para facilitarles el trabajo a sus colegas sin conocimientos técnicos, envíe nombres de propiedad simples y claros. Evite nombres como "property_1" o "base64UUID" a menos que sean etiquetas conocidas en su equipo.
Enviar números, cadenas y valores booleanos
La segmentación Appcues solo puede operar con números, cadenas y booleanos. Puedes enviar objetos complejos en la llamada .identify() de Appcues , pero se ignorarán. No recomendamos enviar objetos a Appcues como propiedad de usuario.
No reformatear los tipos
Envía números como números, cadenas como cadenas, etc. Appcues utiliza inferencia de tipos para coincidir con los criterios de destino, por lo que no es necesario pensar en los tipos. Esto es fundamental al realizar comparaciones, ya que el número 10 es mayor que el número 2, pero ocurre lo contrario si esos valores se convierten en cadenas.

Del mismo modo, si un valor no está definido o es nulo, no lo envíe a Appcues o envíelo como nulo. No envíe una cadena vacía para ningún valor inexistente. Además, las propiedades de cadena distinguen entre mayúsculas y minúsculas.

Por último, asegúrese de que cada propiedad de usuario tenga un tipo consistente. Por ejemplo, "signup_date" (y las propiedades de fecha en general) deben enviarse como una marca de tiempo no fraccionaria (número), como una fecha ISO (cadena) o con el formato MMM, DD, AAAA HH:MM:SS AM/PM (1 de enero de 2025, 22:00:00). Sea cual sea su elección, asegúrese de que sea consistente cada vez que se envíe ese valor a Appcues . La inconsistencia podría resultar en contenido demasiado o demasiado inespecífico para los usuarios.

Appcues utiliza marcas de tiempo UNIX Epoch para fechas y horas internamente.

Si necesita enviar información desde un objeto, aplánelo antes de llamar Appcues .identify(). Por ejemplo, si tuviera una propiedad de usuario llamada "facturas" que fuera una colección de información de facturación, podría reducirla a las siguientes propiedades útiles:

<script>
var invoices = user.invoices || [];
var totalInvoices = invoices.length;
var lastInvoiceDate = (invoices[0] || {}).created_at;
Appcues.identify(user.id, {
  name: user.name,
  email: user.email,
  totalInvoices: totalInvoices,
  lastInvoiceDate: lastInvoiceDate
})
</script>

Restablecer los datos de la sesión de usuario

Aunque no es necesario en la mayoría de los casos, es posible restablecer los datos de la sesión de un usuario llamando Appcues .reset() . Esta llamada borra toda la información conocida sobre el usuario actual en esta sesión. Esta llamada borrará el flujo en curso y cualquier dato generado para un usuario. Esto es útil cuando el usuario cierra sesión en la aplicación.

Nota: Cuando se usa junto con usuarios anónimos Appcues , esto puede provocar que los flujos se muestren dos veces, ya que restablecería la ID generada para ese usuario anónimo.

Eventos de pista

El seguimiento de eventos en Appcues le permite medir la participación y la interacción del usuario y orientar las experiencias en función de esas interacciones, o la falta de ellas, y también ver el impacto de sus experiencias Appcues en los comportamientos de los usuarios.

Ya sea que realice la instalación en nombre de alguien o trabaje directamente dentro de su equipo, lo alentamos a colaborar y seguir un Plan de instalación para delinear qué eventos seguir.

Formas de realizar un seguimiento de eventos

Hay dos maneras de rastrear eventos en Appcues . Independientemente de la forma que elija, le recomendamos usar nombres descriptivos para una fácil comprensión y selección en Studio.

Eventos del lado del cliente/aplicación mediante track()

El seguimiento de eventos se añade directamente a su producto para notificar Appcues sobre un evento exitoso. Este tipo de seguimiento es ideal para cualquier evento de verificación o validación, ya que solo registra la finalización del evento.

Componentes de track()

Nombre del evento ( obligatorio ) : los eventos son únicos según el Event Name , por lo que no reutilice nombres para diferentes eventos.
- Nota: Si instala Appcues en la web y en una aplicación móvil , los nombres de los eventos deben ser diferentes en cada instalación para que se reconozcan como eventos web y móviles. Usar el mismo nombre hará que los eventos se agrupen.
Atributos de evento (opcional) : Proporciona contexto adicional sobre el evento activado. Nota: Los atributos de evento no son visibles en Studio ni en los informes, y solo se pueden usar con la función de activación de eventos .

Ejemplo de llamada a track()

Sin atributos

Appcues.track("Event Name"); // eg "Clicked Some Button"

Con atributos

Appcues.track("Another Event", { // eg "Submitted a Help Ticket"
  url: "/support",
  article:"installation"
});

Notas sobre el seguimiento de eventos mediante track()

Asegúrese de que se haya llamado Appcues .identify() en la página antes de rastrear eventos
Al igual que las propiedades de usuario, Appcues solo recibe los eventos que rastreas explícitamente con Appcues . Es decir, deberás agregar una llamada a track() para cada evento.
Si usa una herramienta de análisis (por ejemplo, Mixpanel, Google Analytics, Heap, Hotjar, etc.), puede agregar una llamada .track() Appcues en cualquier lugar donde ya esté rastreando eventos para esa plataforma.
Se puede agregar Appcues .track() dentro de un controlador de eventos para rastrear el evento cuando se ejecuta la funcionalidad del evento.

Seguimiento de eventos con un clic mediante Appcues Builder

Los eventos CTT no requieren ningún código para su seguimiento y permiten a los usuarios no técnicos crear, controlar y administrar los diferentes eventos dentro de su interfaz de usuario que desean identificar y rastrear.

Consulte nuestro documento Click-to-Track para obtener más información sobre cómo crear y usar eventos CTT

El seguimiento de eventos no completará los datos de eventos.

¿Quieres usar datos históricos? ¡Puedes enviar esa información a través de nuestra API!

Verifique su instalación

A medida que complete cada sección descrita anteriormente, Appcues recomienda revisar el progreso de la instalación para comprobar que cada componente se haya completado correctamente y volver a hacerlo una vez completada. Para revisar y verificar cada paso:

Agregar el script SDK Appcues

Usando el depurador Appcues :

Confirme que Instalado y Conectado a Appcues estén en verde
El depurador Appcues no se abrirá si Appcues no está instalado o detectado . Si ha confirmado que se ha añadido el SDK Appcues , pero el depurador no se abre, puede deberse a varias razones que puede investigar en la consola de su navegador. Puede encontrar más información en la sección "Otras consideraciones" a continuación.
Confirme que las páginas de seguimiento estén en verde
Para confirmar el seguimiento de la página, navegue por su producto con el depurador abierto. A medida que las URL cambian, el indicador de páginas de seguimiento debería cambiar a verde automáticamente. Puede parpadear en rojo mientras la nueva página termina de cargarse; esto no es un problema, siempre que el estado se actualice a verde sin actualizar la página.

Identificar usuarios y grupos

Confirme que el ID de usuario y cualquier propiedad de usuario personalizada se reflejen correctamente en la sección Usuario identificado , y el ID de grupo y cualquier propiedad de grupo personalizada dentro de la sección Grupo identificado del Depurador
Las propiedades personalizadas de usuario y grupo se pueden ver expandiendo los detalles de Usuario identificado y Grupo identificado y desplazándose por las propiedades listadas. Las propiedades automáticas Appcues aparecen primero y se reconocen por su guión bajo inicial (_appcuesId); a continuación, las propiedades personalizadas.

Solo las propiedades personalizadas enviadas mediante identify() y group() serán visibles en el depurador. Las propiedades enviadas mediante una integración solo serán visibles en Studio y se pueden confirmar en la pestaña "Propiedades personalizadas" para las propiedades de usuario y en la página "Propiedades" de una cuenta para las propiedades de grupo.

Eventos de pista

Para eventos .track() Appcues : active el evento o los eventos en el entorno instalado y confirme que aparecen en su página de Eventos (etiquetados como Evento de aplicación importado con SDK ) y/o dentro de su Explorador de eventos con la Fuente del evento establecida en “Eventos de aplicación”.
Nota: Los botones dentro de los flujos que se han rastreado como un evento también aparecerán como un evento de aplicación.
Para eventos de seguimiento de clic ( CTT ) : al crear un CTT en el Constructor Appcues , hay un botón "Probar" para probar el evento sin activarlo por completo. Para activarlo por completo, guarde el CTT e interactúe con él fuera del Constructor.
Estos eventos serán visibles en su página de Eventos (etiquetados como Evento de Seguimiento (Generador) creado en el Generador) y, si aún no se han activado fuera del Generador, la última vez que se vieron se mostrará como "Aún no visto". Los eventos CTT también se pueden ver en el Explorador de Eventos cuando la Fuente del Evento se configura como "Eventos de Seguimiento (Generador)".

¡Instalación inicial completada!

¡Después de completar los pasos descritos anteriormente, la instalación estará completa!

Se recomienda revisar su instalación periódicamente para asegurarse de que todo esté actualizado y que sus propiedades y eventos personalizados respalden sus casos de uso.

Otras consideraciones y recursos

ID de usuarios y grupos con integraciones

Algunas integraciones Appcues tienen requisitos específicos para conectarse correctamente. En muchos casos, el ID de usuario Appcues debe existir como valor en el registro/perfil de la integración. Tenga esto en cuenta al seleccionar el ID de usuario que desea enviar a Appcues . A continuación, se detallan algunos de los requisitos comunes de las integraciones de Appcues :

Fuerza de ventas
- Salesforce <> Appcues : el ID de usuario Appcues debe existir como valor en el objeto Salesforce (contactos, clientes potenciales, etc.)
HubSpot
- HubSpot >> Appcues : el ID de usuario Appcues debe existir como un valor en el registro de HubSpot.
- Appcues >> HubSpot: El VID de HubSpot o el correo electrónico correspondiente debe existir como una propiedad de usuario Appcues (el correo electrónico se puede enviar mediante identificación, desde la sincronización de HubSpot >> Appcues o desde una conexión de fuente de datos)
Marketo
- Marketo >> Appcues : el ID de usuario Appcues debe existir como valor en el registro de Marketo.
- Appcues >> Marketo: el ID del cliente potencial de Marketo o el correo electrónico correspondiente debe existir como una propiedad de usuario Appcues (el correo electrónico se puede enviar a través de la identificación, desde la sincronización de Marketo >> Appcues o desde una conexión de fuente de datos).
Montón
- Heap >> Appcues : el ID de usuario Appcues debe existir como un valor en el perfil de usuario de Heap.
Amplitud
- Amplitud >> Appcues : el ID de usuario Appcues debe existir como una propiedad de usuario en Amplitud.
Panel de mezcla
- Mixpanel >> Appcues : El ID de usuario Appcues debe coincidir con el ID distinto del usuario en Mixpanel.
Alto contacto
- Hightouch >> Appcues : el ID de usuario de su modelo Hightouch debe coincidir con el ID de usuario Appcues enviado en identify().
Censo
- Censo >> Appcues : La clave de sincronización de su modelo de censo debe coincidir con el ID de usuario Appcues enviado en identify().

¿No encuentras tu integración en la lista? Consulta nuestra documentación para ver más integraciones compatibles y confirmar los requisitos.

Razones por las que Appcues pueden no inicializarse o cargarse

Aunque existen diversas razones por las que esto puede ocurrir, la más común es una infracción de la Política de Seguridad de Contenido (CSP). Appcues podría estar siendo bloqueada por CSP de su sitio, lo que provoca un error en la inicialización. Para solucionar esto, puede permitir que la funcionalidad y el diseño de Appcues se carguen correctamente. Más información aquí .

Otras funciones de Javascript Appcues

El SDK Appcues admite funciones adicionales para diversos casos de uso. Más información aquí .

Preguntas frecuentes para desarrolladores

Consulte este documento para obtener preguntas frecuentes al instalar Appcues .

¿Tiene problemas durante la instalación?

¡Revise el documento de solución de problemas para obtener más información o envíenos un correo electrónico a support@appcues.com !

Submit Article Requests