📚 Documentación

v1.0.0

🎮 Introducción

Pokemon Cards SAAS te permite integrar cartas Pokémon relacionadas con tus productos de forma automática en tu tienda e-commerce. Ofrecemos dos tipos de widgets para diferentes necesidades de integración.

🎯 Widget Flotante

Aparece como overlay en la esquina de la pantalla. Ideal para mostrar recomendaciones sin modificar el diseño existente.

📦 Widget Inline

Se integra dentro de elementos específicos de tu página. Perfecto para sidebars, secciones de productos relacionados, etc.

⚡ Instalación y Ubicación

Paso 1: Obtén tu API Key

Ve al dashboard y genera una API key para tu dominio.

📍 Paso 2: ¿Dónde colocar la configuración?

🌐 Sitio Web Normal (HTML)

Coloca el código antes del cierre del </body>:

<!DOCTYPE html>
<html>
<head>
  <title>Mi Tienda</title>
</head>
<body>
  <!-- Tu contenido aquí -->
  
  <!-- AQUÍ VA LA CONFIGURACIÓN -->
  <script>
  window.PokemonCardsConfig = {
    apiKey: 'pk_tu_api_key_aqui',
    theme: 'modern'
  };
  </script>
  <script src="https://tu-dominio.com/pokemon-cards-widget.js"></script>
</body>
</html>

📝 WordPress

En functions.php de tu tema:

// En functions.php
function add_pokemon_widget() {
  if (is_product() || is_single()) {
    ?>
    <script>
    window.PokemonCardsConfig = {
      apiKey: '<?php echo get_option('pokemon_api_key'); ?>',
      theme: 'modern'
    };
    </script>
    <script src="https://tu-dominio.com/pokemon-cards-widget.js"></script>
    <?php
  }
}
add_action('wp_footer', 'add_pokemon_widget');

🛍️ Shopify

En theme.liquid antes del </body>:

<!-- En theme.liquid -->
{% if template contains 'product' %}
<script>
window.PokemonCardsConfig = {
  apiKey: '{{ settings.pokemon_api_key }}',
  theme: 'modern'
};
</script>
<script src="https://tu-dominio.com/pokemon-cards-widget.js"></script>
{% endif %}
</body>
</html>

🛒 PrestaShop / Magento

En el template product.tpl o footer.phtml:

<!-- En product.tpl (PrestaShop) -->
<script>
window.PokemonCardsConfig = {
  apiKey: '{$pokemon_api_key}',
  theme: 'modern'
};
</script>
<script src="https://tu-dominio.com/pokemon-cards-widget.js"></script>

<!-- En footer.phtml (Magento) -->
<script>
window.PokemonCardsConfig = {
  apiKey: '<?php echo $this->getApiKey(); ?>',
  theme: 'modern'
};
</script>

⚠️ Reglas Importantes

La configuración SIEMPRE va ANTES del script

El widget necesita leer la configuración antes de inicializarse.

Solo en páginas de productos

Para mejor rendimiento, carga el widget solo donde lo necesites.

Una sola configuración por página

No dupliques la configuración, el widget se aplicará automáticamente.

✅ Ejemplo Completo - Página de Producto

<!DOCTYPE html>
<html>
<head>
  <title>Auriculares Gaming Pro - Mi Tienda</title>
  <!-- Meta tags para detección automática -->
  <meta property="og:title" content="Auriculares Gaming Pro">
  <meta property="product:category" content="electronics">
</head>
<body>
  <!-- Tu página de producto aquí -->
  <h1>Auriculares Gaming Pro</h1>
  <p>Precio: $129.99</p>
  
  <!-- Para widget inline, añade contenedores donde quieras -->
  <div class="pokemon-cards-container"></div>
  
  <!-- CONFIGURACIÓN AL FINAL, ANTES DE </body> -->
  <script>
  // Widget flotante (aparece automáticamente)
  window.PokemonCardsConfig = {
    apiKey: 'pk_live_1234567890abcdef',
    theme: 'modern',
    maxCards: 3,
    showAnimation: true
  };
  
  // Widget inline (se inyecta en contenedores)
  window.PokemonCardsInlineConfig = {
    apiKey: 'pk_live_1234567890abcdef',
    targetSelector: '.pokemon-cards-container',
    layout: 'horizontal',
    theme: 'inline',
    maxCards: 4,
    customTitle: 'Cartas Pokémon Relacionadas'
  };
  </script>
  
  <!-- SCRIPTS AL FINAL -->
  <script src="https://tu-dominio.com/pokemon-cards-widget.js"></script>
  <script src="https://tu-dominio.com/pokemon-cards-inline-widget.js"></script>
</body>
</html>

🎯 Widget Flotante

El widget flotante aparece automáticamente en la esquina inferior derecha de la pantalla y detecta el producto actual para mostrar cartas Pokémon relacionadas.

Instalación Básica

<!-- Configuración del widget -->
<script>
window.PokemonCardsConfig = {
    apiKey: 'pk_tu_api_key_aqui',
    theme: 'modern',
    maxCards: 3,
    showAnimation: true
};
</script>

<!-- Cargar el widget -->
<script src="https://tu-dominio.com/pokemon-cards-widget.js"></script>

Características

✅ Detección automática de productos
✅ Múltiples temas (modern, dark, minimal)
✅ Animaciones suaves
✅ Responsive design
✅ Click tracking automático

Demo en Vivo

Prueba el widget flotante en nuestra página de demostración:

Ver Demo Flotante →

📦 Widget Inline

El widget inline se integra dentro de elementos específicos de tu página, permitiendo mayor control sobre la ubicación y el diseño.

Instalación Básica

<!-- 1. Crea contenedores donde quieras los widgets -->
<div class="pokemon-cards-container"></div>

<!-- 2. Configura el widget -->
<script>
window.PokemonCardsInlineConfig = {
    apiKey: 'pk_tu_api_key_aqui',
    targetSelector: '.pokemon-cards-container',
    layout: 'horizontal',
    theme: 'inline',
    maxCards: 3,
    customTitle: 'Cartas Pokémon Relacionadas'
};
</script>

<!-- 3. Cargar el widget -->
<script src="https://tu-dominio.com/pokemon-cards-inline-widget.js"></script>

Layout Horizontal

Cartas en fila horizontal con scroll

layout: 'horizontal'

Layout Vertical

Cartas apiladas verticalmente

layout: 'vertical'

Layout Grid

Cuadrícula responsive

layout: 'grid'

Demo Interactivo

Explora todos los layouts y opciones del widget inline:

Ver Demo Inline →

⚙️ Opciones de Configuración

Opción	Tipo	Default	Descripción
apiKey	string	-	Tu API key (requerida)
maxCards	number	3	Número máximo de cartas a mostrar
theme	string	'modern'	Tema visual: 'modern', 'dark', 'minimal', 'inline'
layout	string	'horizontal'	Layout: 'horizontal', 'vertical', 'grid' (solo inline)
targetSelector	string	'.pokemon-cards-container'	Selector CSS para contenedores (solo inline)
showAnimation	boolean	true	Habilitar animaciones
customTitle	'Cartas Pokémon Relacionadas'	string	Título personalizado (solo inline)
autoDetect	boolean	true	Detección automática de productos

💡 Ejemplos de Uso

🛍️ Integración con Shopify

Añade el widget a tu tema de Shopify editando el archivo product.liquid:

<!-- En product.liquid, antes del </body> -->
<div class="pokemon-cards-section">
  <div class="pokemon-cards-container"></div>
</div>

<script>
window.PokemonCardsInlineConfig = {
    apiKey: '{{ settings.pokemon_api_key }}',
    targetSelector: '.pokemon-cards-container',
    layout: 'horizontal',
    maxCards: 4,
    customTitle: 'Cartas Pokémon Relacionadas'
};
</script>
<script src="https://tu-dominio.com/pokemon-cards-inline-widget.js"></script>

🛒 Integración con WooCommerce

Añade el widget usando hooks de WooCommerce en tu functions.php:

// En functions.php
function add_pokemon_cards_widget() {
    ?>
    <div class="pokemon-cards-related">
        <div class="pokemon-cards-container"></div>
    </div>
    
    <script>
    window.PokemonCardsInlineConfig = {
        apiKey: '<?php echo get_option('pokemon_api_key'); ?>',
        targetSelector: '.pokemon-cards-container',
        layout: 'grid',
        maxCards: 6
    };
    </script>
    <script src="https://tu-dominio.com/pokemon-cards-inline-widget.js"></script>
    <?php
}
add_action('woocommerce_after_single_product_summary', 'add_pokemon_cards_widget', 25);

⚡ Control Programático

Controla el widget dinámicamente con JavaScript:

// Crear widget dinámicamente
const widget = new PokemonCardsInlineWidget({
    apiKey: 'tu_api_key',
    targetSelector: '.dynamic-container',
    layout: 'vertical',
    maxCards: 5
});

// Escuchar eventos de click
document.addEventListener('pokemonCardClick', function(event) {
    console.log('Carta clickeada:', event.detail.cardId);
    // Añadir al carrito, mostrar modal, etc.
});

// Actualizar configuración
widget.updateConfig({
    theme: 'dark',
    maxCards: 8
});

// Refrescar widget
widget.refresh();

// Destruir widget
widget.destroy();

🔌 API Reference

Métodos Disponibles

widget.refresh()

Recarga el widget con nuevos datos

widget.destroy()

Elimina el widget del DOM

widget.updateConfig(newConfig)

Actualiza la configuración del widget

Eventos Personalizados

pokemonCardClick

Se dispara cuando se hace click en una carta

document.addEventListener('pokemonCardClick', function(event) {
    console.log(event.detail.cardId);
    console.log(event.detail.cardElement);
    console.log(event.detail.widget);
});

Detección de Productos

El widget detecta automáticamente productos usando múltiples estrategias:

• Meta tags Open Graph y Twitter Cards
• Structured Data (JSON-LD)
• Selectores CSS comunes (.product-title, h1, etc.)
• Análisis de URL

🆘 Soporte y Ayuda

📧 Contacto

¿Necesitas ayuda con la integración? Contáctanos:

• Email: soporte@pokemoncards-saas.com
• Discord: #pokemon-cards-support
• Documentación: /docs

🔧 Solución de Problemas

Widget no aparece:

Verifica tu API key y que el dominio esté autorizado

Cartas no relacionadas:

Asegúrate de que los meta tags del producto estén configurados

Errores de CORS:

Verifica que el dominio esté registrado en tu API key

🚀 Próximas Funcionalidades

🎨

Más Temas

Temas personalizables y branded

📊

Analytics Avanzados

Métricas detalladas de engagement

🤖

IA Mejorada

Mejor detección de productos