SDK de Tutoriais Interativos

Adicione tutoriais interativos step-by-step no seu produto. Seus usuários aprendem fazendo, direto dentro do app.

Quick Start (2 minutos)

Cole o snippet abaixo no <head> do seu site:

<script
  src="https://app.stepyo.com.br/sdk.js"
  data-api-key="SUA_API_KEY"
  data-lang="pt-BR"
  async
></script>

Pronto. O widget de ajuda aparece automaticamente no canto inferior direito.

Instalação

Script tag (recomendado)

A forma mais simples. Funciona com qualquer framework ou site estático.

<script
  src="https://app.stepyo.com.br/sdk.js"
  data-api-key="SUA_API_KEY"
  data-lang="pt-BR"
  data-position="bottom-right"
  data-color="#EC4899"
  data-button-text="Precisa de ajuda?"
  data-title="Central de Ajuda"
  data-icon="help"
  data-user-id="user_123"
  data-user-email="[email protected]"
  async
></script>

React / Next.js

// components/StepyoWidget.tsx
'use client';
import { useEffect } from 'react';

export function StepyoWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://app.stepyo.com.br/sdk.js';
    script.async = true;
    script.dataset.apiKey = process.env.NEXT_PUBLIC_STEPYO_KEY!;
    script.dataset.lang = 'pt-BR';
    document.head.appendChild(script);

    return () => {
      (window as any).Stepyo?.destroy();
      script.remove();
    };
  }, []);

  return null;
}

// No layout: <StepyoWidget />

Vue / Nuxt

<!-- StepyoWidget.vue -->
<script setup>
import { onMounted, onUnmounted } from 'vue';

const props = defineProps({ apiKey: String });

onMounted(() => {
  const s = document.createElement('script');
  s.src = 'https://app.stepyo.com.br/sdk.js';
  s.dataset.apiKey = props.apiKey;
  s.async = true;
  document.head.appendChild(s);
});

onUnmounted(() => window.Stepyo?.destroy());
</script>

API JavaScript

Todos os métodos estão disponíveis em window.Stepyo:

Stepyo.init(config)

Inicializa a SDK manualmente (alternativa ao auto-init via script tag).

Stepyo.init({
  apiKey: 'your_api_key_here',
  lang: 'pt-BR',           // 'pt-BR' | 'en'
  position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  primaryColor: '#EC4899',  // hex
  buttonText: 'Ajuda',      // texto do botão (vazio = só ícone)
  panelTitle: 'Tutoriais',
  buttonIcon: 'help',       // 'help'|'chat'|'book'|'zap'|'sparkles'|'headphones' ou URL
});

Stepyo.identify(user)

Associa eventos da SDK com o usuário do seu app. Chame após login.

Stepyo.identify({
  userId: 'user_123',
  email: '[email protected]',
  name: 'João Silva',
  traits: { role: 'admin', plan: 'pro' }
});

Stepyo.startFlow(flowKey)

Inicia um tutorial específico por código. Ideal para onboarding contextual.

// Disparar tutorial quando usuário cria conta
Stepyo.startFlow('welcome-tour');

Stepyo.openPanel() / Stepyo.closePanel()

Abre ou fecha o painel de tutoriais programaticamente.

Stepyo.isReady()

Retorna true quando a SDK terminou de carregar.

Stepyo.on(event, callback) / Stepyo.off(event, callback)

Escuta eventos da SDK.

Stepyo.on('flow:completed', (data) => {
  console.log('Tutorial concluído:', data.flowKey);
  // Marcar onboarding como completo no seu backend
});

Stepyo.on('ready', () => {
  // SDK carregou, seguro usar startFlow
});

Stepyo.destroy()

Remove o widget e limpa listeners. Use em SPAs ao desmontar componente.

Eventos

Evento	Data	Quando dispara
`ready`	-	SDK inicializada
`flow:started`	`{flowKey, flowName}`	Tutorial iniciou
`flow:completed`	`{flowKey}`	Tutorial concluído
`flow:cancelled`	`{flowKey, lastStep}`	Usuário cancelou
`step:changed`	`{flowKey, stepIndex, totalSteps}`	Avançou/voltou step
`step:failed`	`{flowKey, stepIndex, error}`	Elemento não encontrado
`panel:opened`	-	Painel de tutoriais abriu
`panel:closed`	-	Painel fechou

Customização

Via data attributes

Atributo	Tipo	Descrição
`data-api-key`	string	Chave da API (obrigatório)
`data-lang`	`pt-BR \| en`	Idioma (default: pt-BR)
`data-position`	string	Posição do botão
`data-color`	hex	Cor primária do widget
`data-button-text`	string	Texto no botão (vazio = só ícone)
`data-title`	string	Título do painel
`data-icon`	string	Ícone preset ou URL
`data-user-id`	string	ID do usuário
`data-user-email`	string	Email do usuário
`data-user-name`	string	Nome do usuário

Deep linking

Abra um tutorial específico via URL:

https://seuapp.com/dashboard?stepyo-flow=welcome-tour

Segurança

API Keys

Keys são hasheadas com SHA-256 no servidor (nunca armazenadas em texto)
A key completa é mostrada apenas uma vez (na criação)
Keys podem ser desativadas ou deletadas a qualquer momento

Domínios permitidos

Configure quais domínios podem usar sua API key
Suporta wildcards: *.seudominio.com
Requests de domínios não permitidos são bloqueados (CORS)

Rate limiting

Default: 60 requests/minuto por key
Configurável por key no dashboard

FAQ

O widget afeta a performance do meu site?

O bundle tem ~12KB gzip. Carrega de forma assíncrona (async) e não bloqueia a renderização. Usa Shadow DOM para isolamento total de CSS.

Funciona com SPAs (React, Vue, Angular)?

Sim. A SDK detecta navegações client-side e persiste o estado do tutorial entre páginas via sessionStorage.

Como crio tutoriais?

Use a extensão Chrome do Stepyo para gravar tutoriais no seu produto. Depois converta em flow e ative para SDK no dashboard.

Posso esconder o botão e disparar flows por código?

Sim. Use Stepyo.startFlow('key') para disparar tutoriais programaticamente. Para esconder o botão flutuante, não configure data-button-text e use CSS para ocultar se necessário.

Os dados dos meus usuários são seguros?

A SDK envia apenas os dados que você passar via identify(). Nenhum dado pessoal é coletado automaticamente. Eventos são armazenados por 90 dias e acessíveis apenas via seu dashboard.