Documentação Oopsie

Integre a Oopsie com clareza, do primeiro snippet à validação.

Escolha sua stack, siga a ordem recomendada e use os arquivos e placeholders indicados para concluir a integração sem adivinhação.

Ver passo a passo Ver stacks

7 stacks cobertas

3 fluxos de integração

1 fluxo para conectar browser, backend e release

Como seguir esta documentação

A página prioriza o que mais costuma gerar dúvida: onde colar o código, o que trocar antes do teste e como validar a primeira captura.

Escolha uma stack por vez

Comece pela camada que realmente inicia a aplicação: backend, browser ou ambas.

Encontre o arquivo principal

Se o projeto usar nomes diferentes, localize o arquivo que sobe a aplicação ou concentra o tratamento global de erros.

Cole, substitua e valide

Cole o trecho sugerido, troque os placeholders e gere um erro de teste para confirmar a integração.

Guias por linguagem e framework

Cada stack mostra a ordem recomendada, os arquivos mais prováveis, os valores que precisam ser trocados e um exemplo simples de release.

Browser + Backend

Laravel

Instale o pacote `oopsie/oopsie-laravel`, publique a configuração, preencha o .env e limpe o cache da aplicação.

Mais indicado para Aplicações Laravel com fluxo web, API ou painéis internos.

Arquivos mais prováveis

app/Exceptions/Handler.php bootstrap/app.php

Troque antes de usar

YOUR_PROJECT_TOKEN YOUR_PROJECT_KEY YOUR_RELEASE_TOKEN

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

composer require oopsie/oopsie-laravel
php artisan vendor:publish --tag=oopsie-config

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: app/Exceptions/Handler.php, bootstrap/app.php

Conecta a captura ao ponto principal da aplicação.

public function report(Throwable $e): void
{
    try {
        \Oopsie::captureException($e);
    } catch (Throwable $ignore) {
        // Keep the original Laravel flow if capture fails.
    }

    parent::report($e);
}

Passo 3: configurar o ambiente Use em um destes arquivos, escolhendo apenas um: .env

Mantém tokens e URLs fora do código.

OOPSIE_PROJECT_TOKEN=YOUR_PROJECT_TOKEN
OOPSIE_PROJECT_KEY=YOUR_PROJECT_KEY
OOPSIE_BASE_URL=https://www.oopsie.com.br
OOPSIE_HANDSHAKE_URL=https://www.oopsie.com.br/api/sdk/handshake
OOPSIE_RELEASE_TOKEN=YOUR_RELEASE_TOKEN
OOPSIE_ENV=production
OOPSIE_RELEASE=1.0.0
OOPSIE_DSN=https://www.oopsie.com.br/api/capture

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: deploy.sh, GitHub Actions, pipeline CI

Registra a versão ou o deploy no painel.

php artisan oopsie:notify-release

Notas

No Laravel, este passo liga o fluxo de exceções do app à Oopsie. Sem ele, a SDK pode estar instalada, mas os erros do servidor podem não chegar ao painel.

Backend SDK

PHP

Para PHP puro, instale `oopsie/oopsie-php` e adapte o init ao bootstrap real, front controller, worker ou script principal. O handshake backend já vai junto no `Oopsie::install()`.

Mais indicado para Projetos PHP sem framework ou com bootstrap próprio.

Arquivos mais prováveis

public/index.php bootstrap/app.php config/bootstrap.php

Troque antes de usar

YOUR_PROJECT_TOKEN YOUR_PROJECT_KEY YOUR_RELEASE_TOKEN

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

composer require oopsie/oopsie-php

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: public/index.php, bootstrap/app.php, config/bootstrap.php

Conecta a captura ao ponto principal da aplicação.

\Oopsie\Sdk\Oopsie::install('YOUR_PROJECT_TOKEN', [
    'projectKey' => 'YOUR_PROJECT_KEY',
    'baseUrl' => 'https://www.oopsie.com.br',
    'handshakeUrl' => 'https://www.oopsie.com.br/api/sdk/handshake',
    'release' => getenv('OOPSIE_RELEASE') ?: '1.0.0',
    'releaseToken' => 'YOUR_RELEASE_TOKEN',
]);

Passo 3: configurar o ambiente Use em um destes arquivos, escolhendo apenas um: .env, variaveis do servidor

Mantém tokens e URLs fora do código.

OOPSIE_RELEASE=1.0.0
OOPSIE_ENV=production

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: deploy.sh, GitHub Actions, pipeline CI

Registra a versão ou o deploy no painel.

\Oopsie\Sdk\Oopsie::notifyRelease([
    'projectKey' => 'YOUR_PROJECT_KEY',
    'releaseToken' => 'YOUR_RELEASE_TOKEN',
    'baseUrl' => 'https://www.oopsie.com.br',
    'version' => getenv('OOPSIE_RELEASE') ?: '1.0.0',
    'environment' => getenv('APP_ENV') ?: 'production',
    'commitSha' => getenv('OOPSIE_COMMIT_SHA') ?: null,
]);

Notas

Para PHP puro ou legado, adicione o snippet da SDK Browser no layout principal, template compartilhado ou header global da aplicação. Nessa stack você não precisa de npm nem import.

Backend SDK

Node.js

Para Node.js, instale `@oopsie-app/node`, inicialize a SDK no bootstrap do servidor e conecte o handler de erro do framework. O handshake inicial já é enviado pela SDK.

Mais indicado para APIs, BFFs e servidores Node.js com Express ou camada HTTP própria.

Arquivos mais prováveis

server.js app.js index.js src/server.ts

Troque antes de usar

YOUR_PROJECT_TOKEN YOUR_PROJECT_KEY YOUR_RELEASE_TOKEN

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

npm install @oopsie-app/node

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: server.js, app.js, index.js, src/server.ts

Conecta a captura ao ponto principal da aplicação.

const { createOopsieNode } = require('@oopsie-app/node');

const oopsie = createOopsieNode({
  apiToken: 'YOUR_PROJECT_TOKEN',
  projectKey: 'YOUR_PROJECT_KEY',
  captureUrl: 'https://www.oopsie.com.br/api/capture',
  handshakeUrl: 'https://www.oopsie.com.br/api/sdk/handshake',
  releaseUrl: 'https://www.oopsie.com.br/api/releases',
  releaseToken: 'YOUR_RELEASE_TOKEN',
  environment: process.env.NODE_ENV || 'production',
  release: process.env.OOPSIE_RELEASE || '1.0.0',
  framework: 'express',
});

oopsie.handshake().catch(() => {});

app.use(oopsie.expressRequestHandler());
app.use(oopsie.expressErrorHandler());

Passo 3: configurar o ambiente Use em um destes arquivos, escolhendo apenas um: .env, painel da hospedagem

Mantém tokens e URLs fora do código.

OOPSIE_PROJECT_TOKEN=YOUR_PROJECT_TOKEN
OOPSIE_PROJECT_KEY=YOUR_PROJECT_KEY
OOPSIE_RELEASE_TOKEN=YOUR_RELEASE_TOKEN
NODE_ENV=production
OOPSIE_RELEASE=1.0.0

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: deploy.sh, GitHub Actions, pipeline CI

Registra a versão ou o deploy no painel.

await oopsie.notifyRelease({
  version: process.env.OOPSIE_RELEASE || '1.0.0',
  environment: process.env.NODE_ENV || 'production',
  commitSha: process.env.OOPSIE_COMMIT_SHA,
  description: 'Deploy production',
});

Notas

Se o projeto também renderiza interface web, complemente depois com o SDK browser para fechar o contexto frontend + backend.

Browser SDK

JavaScript

Instale o pacote oficial `@oopsie-app/browser` e inicialize a SDK no entrypoint principal do frontend.

Mais indicado para Frontends simples, landing pages ou apps sem framework SPA.

Arquivos mais prováveis

src/main.js src/app.js public/index.html

Troque antes de usar

YOUR_PROJECT_KEY

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

npm install @oopsie-app/browser

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: src/main.js, src/app.js, public/index.html

Conecta a captura ao ponto principal da aplicação.

import { init } from '@oopsie-app/browser';

const oopsieConfig = {
  projectKey: 'YOUR_PROJECT_KEY',
  endpoint: 'https://www.oopsie.com.br/api/capture',
  handshakeEndpoint: 'https://www.oopsie.com.br/api/sdk/handshake',
  replayEndpoint: 'https://www.oopsie.com.br/api/replay',
  env: 'production',
  release: window.__APP_VERSION__ || '1.0.0',
  sessionReplaySampleRate: 0.1,
  sessionReplayOnErrorSampleRate: 1.0,
};

init(oopsieConfig);

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: src/main.js, src/app.js, public/index.html

Registra a versão ou o deploy no painel.

window.__APP_VERSION__ = '1.0.0';

Notas

Use este snippet apenas se o projeto não usar npm, bundler ou package manager.

Browser SDK

React

Instale `@oopsie-app/browser` e `@oopsie-app/react`, depois envolva a aplicação com o `OopsieProvider`.

Mais indicado para Aplicações React com provider, boundary e bootstrap centralizado.

Arquivos mais prováveis

src/main.jsx src/index.jsx src/App.jsx

Troque antes de usar

YOUR_PROJECT_KEY

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

npm install @oopsie-app/browser @oopsie-app/react

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: src/main.jsx, src/index.jsx, src/App.jsx

Conecta a captura ao ponto principal da aplicação.

import { OopsieProvider, OopsieErrorBoundary } from '@oopsie-app/react';

const oopsieConfig = {
  projectKey: 'YOUR_PROJECT_KEY',
  endpoint: 'https://www.oopsie.com.br/api/capture',
  handshakeEndpoint: 'https://www.oopsie.com.br/api/sdk/handshake',
  replayEndpoint: 'https://www.oopsie.com.br/api/replay',
  env: 'production',
  release: window.__APP_VERSION__ || '1.0.0',
  sessionReplaySampleRate: 0.1,
  sessionReplayOnErrorSampleRate: 1.0,
};

root.render(
  <OopsieProvider config={oopsieConfig}>
    <OopsieErrorBoundary fallback={<div>Something went wrong.</div>}>
      <App />
    </OopsieErrorBoundary>
  </OopsieProvider>
);

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: src/main.jsx, src/index.jsx, pipeline de build

Registra a versão ou o deploy no painel.

window.__APP_VERSION__ = '1.0.0';

Notas

Seu fluxo principal nesta stack é o browser. Use a SDK backend apenas se existir API, BFF ou servidor PHP no mesmo projeto.

Browser SDK

Vue

Instale `@oopsie-app/browser` e `@oopsie-app/vue`, depois registre o plugin no bootstrap principal da aplicação.

Mais indicado para Apps Vue com plugin global no bootstrap principal.

Arquivos mais prováveis

src/main.js src/main.ts

Troque antes de usar

YOUR_PROJECT_KEY

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

npm install @oopsie-app/browser @oopsie-app/vue

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: src/main.js, src/main.ts

Conecta a captura ao ponto principal da aplicação.

import { createOopsieVue } from '@oopsie-app/vue';

const oopsieConfig = {
  projectKey: 'YOUR_PROJECT_KEY',
  endpoint: 'https://www.oopsie.com.br/api/capture',
  handshakeEndpoint: 'https://www.oopsie.com.br/api/sdk/handshake',
  replayEndpoint: 'https://www.oopsie.com.br/api/replay',
  env: 'production',
  release: window.__APP_VERSION__ || '1.0.0',
  sessionReplaySampleRate: 0.1,
  sessionReplayOnErrorSampleRate: 1.0,
};

app.use(createOopsieVue({
  config: oopsieConfig,
}));

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: src/main.js, src/main.ts, pipeline de build

Registra a versão ou o deploy no painel.

window.__APP_VERSION__ = '1.0.0';

Notas

Seu fluxo principal nesta stack é o browser. Use a SDK backend apenas se existir API, BFF ou servidor PHP no mesmo projeto.

Browser + Backend

WordPress

Para WordPress, trate este pacote como base PHP e encaixe a inicialização no plugin, tema ou hook central do projeto.

Mais indicado para Plugins, temas ou instalações WordPress com fluxo misto de backend + browser.

Arquivos mais prováveis

wp-config.php functions.php plugin-principal.php

Troque antes de usar

YOUR_PROJECT_TOKEN YOUR_PROJECT_KEY YOUR_RELEASE_TOKEN

Passo 1: instalar o SDK Execute este comando no terminal do projeto.

Instala o SDK e libera os arquivos base da stack.

composer require oopsie/oopsie-php

Passo 2: ligar a captura Use em um destes arquivos, escolhendo apenas um: wp-config.php, functions.php, plugin-principal.php

Conecta a captura ao ponto principal da aplicação.

add_action('init', function () {
    \Oopsie\Sdk\Oopsie::install('YOUR_PROJECT_TOKEN', [
        'projectKey' => 'YOUR_PROJECT_KEY',
        'baseUrl' => 'https://www.oopsie.com.br',
        'handshakeUrl' => 'https://www.oopsie.com.br/api/sdk/handshake',
        'release' => defined('OOPSIE_RELEASE') ? OOPSIE_RELEASE : '1.0.0',
        'releaseToken' => 'YOUR_RELEASE_TOKEN',
    ]);
});

Passo 3: configurar o ambiente Use em um destes arquivos, escolhendo apenas um: wp-config.php, variaveis do servidor

Mantém tokens e URLs fora do código.

OOPSIE_RELEASE=1.0.0
OOPSIE_ENV=production

Passo 4: registrar release Use em um destes arquivos, escolhendo apenas um: plugin-principal.php, deploy.sh, pipeline CI

Registra a versão ou o deploy no painel.

\Oopsie\Sdk\Oopsie::notifyRelease([
    'projectKey' => 'YOUR_PROJECT_KEY',
    'releaseToken' => 'YOUR_RELEASE_TOKEN',
    'baseUrl' => 'https://www.oopsie.com.br',
    'version' => defined('OOPSIE_RELEASE') ? OOPSIE_RELEASE : '1.0.0',
    'environment' => wp_get_environment_type(),
]);

Notas

Adicione o snippet da SDK Browser no tema, header global ou layout compartilhado do WordPress. Não use import aqui a menos que exista um frontend separado com bundler.