Mobile

Os SDKs mobile da Solomon permitem rastrear os mesmos 8 eventos de funil do SDK web, enviando dados idênticos para o backend — sem necessidade de qualquer alteração no servidor. Estão disponíveis para React Native (bare e Expo managed) e Flutter/Dart.

React Native

Pacote @solomon-tech/events-react-native no npm.

Flutter

Pacote solomon_events no pub.dev.

A inicialização do SDK requer os mesmos parâmetros do SDK web, com algumas adições específicas para mobile.

string

É o ID de 20 caracteres que a loja possui na Solomon.

boolean

Parâmetro opcional para ativar os logs de debug no console.

boolean

default:"true"

Controla o envio dos eventos para o pixel, necessário para a atribuição. Vem ligado por padrão — defina false explicitamente para desativar.

A funcionalidade de atribuição só irá funcionar se os eventos forem enviados para o pixel.

string

Parâmetro opcional com o Bundle ID do app (ex: com.suaempresa.app). Usado no campo current_domain dos eventos de atribuição.

StorageAdapter

Parâmetro opcional para substituir o storage padrão (AsyncStorage no React Native, SharedPreferences no Flutter) por um adapter customizado. A interface exige três métodos — getItem, setItem e removeItem — todos assíncronos.

function

Callback opcional chamado quando um link da Solomon (l.solomon.com.br/...) é aberto e resolvido. Recebe (deepLinkValue, params) — use o deepLinkValue para rotear o usuário até a tela certa dentro do app. Essencial para os App Links / Universal Links (ver o guia de App Links).

string

default:"l.solomon.com.br"

Domínio dos links da Solomon. Deep links desse host são resolvidos automaticamente no servidor (utm + deep link + click_id). Só altere se usar um domínio de link customizado.

No Flutter esses mesmos parâmetros são passados via SolomonConfig na construção do SolomonSDK.

Instalação

React Native
Flutter

Instale o pacote do SDK e a dependência obrigatória de storage.

Terminal

npm install @solomon-tech/events-react-native @react-native-async-storage/async-storage

Opcionalmente, instale as dependências nativas para telemetria completa do device.

Terminal

npm install react-native-device-info @react-native-community/netinfo react-native-install-referrer react-native-keychain

Essas dependências são opcionais. Sem elas o SDK funciona normalmente, mas campos como device_id, device_model, connection_type e install_referrer serão preenchidos com valores padrão. Sem react-native-keychain, a identidade do usuário no iOS não sobrevive à reinstalação do app (no Android a durabilidade já vem do identificador do device).

No iOS, instale os pods nativos.

Terminal

cd ios && pod install && cd ..

Para Expo managed workflow, adicione os config plugins no app.json para cada dependência opcional instalada:

app.json

{
  "expo": {
    "plugins": [
      "react-native-device-info",
      "@react-native-community/netinfo"
    ]
  }
}

Adicione o pacote ao projeto.

Terminal

flutter pub add solomon_events

No iOS, os pods são instalados automaticamente no próximo flutter run/flutter build. Se necessário, force manualmente:

Terminal

cd ios && pod install && cd ..

Diferente do React Native, o SDK Flutter já traz todas as dependências nativas (device info, connectivity, secure storage, install referrer e app_links). Não há passo de instalação opcional — a telemetria completa do device funciona out of the box.

Inicialização

React Native
Flutter

O padrão recomendado é criar um contexto React para disponibilizar o SDK em toda a aplicação.

Crie o contexto e o provider do SDK.

SolomonContext.tsx

import React, { createContext, useContext, useEffect, useState } from 'react';
import { SolomonSDK } from '@solomon-tech/events-react-native';

const SolomonContext = createContext<SolomonSDK | null>(null);

export function SolomonProvider({ children }: { children: React.ReactNode }) {
  const [sdk, setSdk] = useState<SolomonSDK | null>(null);

  useEffect(() => {
    const instance = new SolomonSDK({
      companyId: 'SEU_COMPANY_ID',
      debug: true,
      useTouchpoint: true,
      appIdentifier: 'com.suaempresa.app',
      // Chamado quando um link da Solomon abre o app — use para rotear a tela.
      onDeepLink: (deepLinkValue) => {
        if (deepLinkValue) {
          // ex.: navigation.navigate(...) com base no deepLinkValue
        }
      },
    });

    setSdk(instance);

    return () => instance.destroy();
  }, []);

  if (!sdk) return null;

  return (
    <SolomonContext.Provider value={sdk}>
      {children}
    </SolomonContext.Provider>
  );
}

export function useSolomon(): SolomonSDK {
  const context = useContext(SolomonContext);
  if (!context) {
    throw new Error('useSolomon deve ser usado dentro de um SolomonProvider');
  }
  return context;
}

Envolva a aplicação com o provider.

App.tsx

import { SolomonProvider } from './contexts/SolomonContext';

export default function App() {
  return (
    <SolomonProvider>
      {/* resto da aplicação */}
    </SolomonProvider>
  );
}

Crie a instância do SDK no main() e envolva o app com SolomonDeepLinks (captura os deep links) e o SolomonNavigatorObserver (rastreia telas).

Inicialize o SDK antes de rodar o app.

main.dart

import 'package:flutter/material.dart';
import 'package:solomon_events/solomon_events.dart';

late final SolomonSDK solomon;

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  solomon = SolomonSDK(SolomonConfig(
    companyId: 'SEU_COMPANY_ID',
    debug: true,
    useTouchpoint: true,
    appIdentifier: 'com.suaempresa.app',
    // Chamado quando um link da Solomon abre o app — use para rotear a tela.
    onDeepLink: (deepLinkValue, params) {
      if (deepLinkValue.isNotEmpty) {
        // ex.: navigator.pushNamed(...) com base no deepLinkValue
      }
    },
  ));

  runApp(const MyApp());
}

Envolva o MaterialApp com SolomonDeepLinks e registre o observer de navegação.

MyApp.dart

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return SolomonDeepLinks(
      sdk: solomon,
      child: MaterialApp(
        navigatorObservers: [SolomonNavigatorObserver(solomon)],
        home: const HomePage(),
      ),
    );
  }
}

Rastreamento de telas

Para o SDK saber qual tela o usuário está visualizando, a configuração pode ser feita manualmente ou automaticamente pelo roteador de navegação.

React Native
Flutter

Manualmente

Chame setScreenName sempre que o usuário navegar para uma nova tela.

ProductScreen.tsx

import { useEffect } from 'react';
import { useSolomon } from '../contexts/SolomonContext';

export function ProductScreen() {
  const solomon = useSolomon();

  useEffect(() => {
    solomon.setScreenName('ProductScreen');
    solomon.track('VIEW_PAGE');
  }, [solomon]);

  return (/* ... */);
}

Se você usa React Navigation, o hook useSolomonScreenTracking atualiza o nome da tela automaticamente via setScreenName. O disparo de VIEW_PAGE continua sendo responsabilidade de cada tela.

App.tsx

import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import { SolomonProvider, useSolomon } from './contexts/SolomonContext';
import { useSolomonScreenTracking } from '@solomon-tech/events-react-native/hooks';

function AppNavigator() {
  const solomon = useSolomon();
  const navigationRef = useNavigationContainerRef();
  const onStateChange = useSolomonScreenTracking(solomon, navigationRef);

  return (
    <NavigationContainer ref={navigationRef} onStateChange={onStateChange}>
      {/* suas telas */}
    </NavigationContainer>
  );
}

export default function App() {
  return (
    <SolomonProvider>
      <AppNavigator />
    </SolomonProvider>
  );
}

Manualmente

Chame setScreenName sempre que o usuário navegar para uma nova tela.

product_screen.dart

class _ProductScreenState extends State<ProductScreen> {
  @override
  void initState() {
    super.initState();
    solomon.setScreenName('ProductScreen');
    solomon.track(SolomonEvent.viewPage);
  }

  // ...
}

Com o NavigatorObserver

Se você registrou o SolomonNavigatorObserver no MaterialApp (ver Inicialização), o nome da tela é atualizado automaticamente pelo name de cada rota (RouteSettings.name). O disparo de VIEW_PAGE continua sendo responsabilidade de cada tela.

MaterialApp(
  navigatorObservers: [SolomonNavigatorObserver(solomon)],
  // Use rotas nomeadas para o observer capturar o nome da tela:
  onGenerateRoute: (settings) { /* ... */ },
);

Deep links e UTMs

Para que a detecção de pontos de contato funcione corretamente, o SDK precisa ler os deep links — URLs que abrem o app diretamente (ex: https://sualoja.com/produto?utm_source=google&utm_medium=cpc). Você pode configurar manualmente ou utilizar o wrapper disponibilizado dentro do pacote.

React Native
Flutter

Manualmente

App.tsx

import { useEffect } from 'react';
import { Linking } from 'react-native';
import { useSolomon } from './contexts/SolomonContext';

function DeepLinkHandler() {
  const solomon = useSolomon();

  useEffect(() => {
    Linking.getInitialURL().then(url => {
      if (url) solomon.handleDeepLink(url);
    });

    const subscription = Linking.addEventListener('url', event => {
      solomon.handleDeepLink(event.url);
    });

    return () => subscription.remove();
  }, [solomon]);

  return null;
}

Com o hook

App.tsx

import { useSolomonDeepLinks } from '@solomon-tech/events-react-native/hooks';
import { useSolomon } from './contexts/SolomonContext';

function DeepLinkHandler() {
  const solomon = useSolomon();
  useSolomonDeepLinks(solomon);
  return null;
}

O jeito recomendado é envolver o app com SolomonDeepLinks (ver Inicialização) — ele já trata o link inicial e o stream de links via app_links, chamando handleDeepLink automaticamente.

SolomonDeepLinks(
  sdk: solomon,
  child: MaterialApp(/* ... */),
);

Manualmente

Se preferir controlar você mesmo, use o app_links e chame handleDeepLink:

import 'package:app_links/app_links.dart';

final appLinks = AppLinks();

// Link que abriu o app (cold start)
appLinks.getInitialLink().then((uri) {
  if (uri != null) solomon.handleDeepLink(uri.toString());
});

// Links recebidos com o app aberto
appLinks.uriLinkStream.listen((uri) => solomon.handleDeepLink(uri.toString()));

Para os links da Solomon (l.solomon.com.br/..., criados em Integrações → App Links), o SDK resolve o link no servidor automaticamente ao recebê-lo: recupera a UTM, o click_id e o deep link value (a rota in-app), mesmo quando esses dados não vêm na URL. É por isso que você define o onDeepLink na inicialização — é nele que o deepLinkValue chega para você rotear a tela. Para o app abrir esses links direto (sem passar pelo navegador), configure os App Links / Universal Links — ver o guia de App Links.

Os parâmetros de UTM extraídos de deep links são persistidos no device e enviados em todos os eventos subsequentes, até que um novo deep link com UTMs diferentes seja recebido.

Disparando eventos

A chamada track funciona de forma idêntica ao SDK web. Os mesmos 8 tipos de evento estão disponíveis.

React Native
Flutter

Dispare o evento de visualização de página.

solomon.track('VIEW_PAGE');

Dispare eventos com payload e aliases.

// Visualização de produto
await solomon.track('CONTENT_VIEW', {
  id: 'produto-123',
  title: 'Camiseta Azul',
  price: 49.90,
  variant: 'M',
});

// Adição ao carrinho
await solomon.track('ADD_TO_CART', {
  item_id: 'produto-123',
  item_quantity: 2,
});

// Checkout completo com aliases
await solomon.track('CHECKOUT_COMPLETED', {
  items: [{ item_id: 'produto-123', item_quantity: 2 }],
}, {
  email: 'cliente@exemplo.com',
  order_id: 'PED-456',
  phone: '11999999999',
});

Os campos disponíveis em aliases são: email, phone, user_id, customer_id, cart_token e order_id.

Dispare o evento de visualização de página.

solomon.track(SolomonEvent.viewPage);

Dispare eventos com payload e aliases.

// Visualização de produto
await solomon.track(SolomonEvent.contentView, payload: {
  'id': 'produto-123',
  'title': 'Camiseta Azul',
  'price': 49.90,
  'variant': 'M',
});

// Adição ao carrinho
await solomon.track(SolomonEvent.addToCart, payload: {
  'item_id': 'produto-123',
  'item_quantity': 2,
});

// Checkout completo com aliases
await solomon.track(SolomonEvent.checkoutCompleted, payload: {
  'items': [{'item_id': 'produto-123', 'item_quantity': 2}],
}, aliases: {
  'email': 'cliente@exemplo.com',
  'order_id': 'PED-456',
  'phone': '11999999999',
});

Os campos disponíveis em aliases são: email, phone, user_id, customer_id, cart_token e order_id.

A chamada track é assíncrona. O monitoramento de erros deve ser feito por meio do console, com a opção debug ativada na configuração do SDK.

Storage customizado

Por padrão, o SDK persiste dados no storage nativo da plataforma. Se preferir uma solução mais performática, basta passar um adapter customizado na inicialização.

React Native
Flutter

Padrão: AsyncStorage. Exemplo substituindo por MMKV:

import { MMKV } from 'react-native-mmkv';

const mmkv = new MMKV();

const sdk = new SolomonSDK({
  companyId: 'SEU_COMPANY_ID',
  storage: {
    getItem: (key) => Promise.resolve(mmkv.getString(key) ?? null),
    setItem: (key, value) => { mmkv.set(key, value); return Promise.resolve(); },
    removeItem: (key) => { mmkv.delete(key); return Promise.resolve(); },
  },
});

Padrão: SharedPreferences. Implemente StorageAdapter para usar outra solução:

class MyStorage implements StorageAdapter {
  @override
  Future<String?> getItem(String key) async { /* ... */ }

  @override
  Future<void> setItem(String key, String value) async { /* ... */ }

  @override
  Future<void> removeItem(String key) async { /* ... */ }
}

final sdk = SolomonSDK(SolomonConfig(
  companyId: 'SEU_COMPANY_ID',
  storage: MyStorage(),
));

Primeiros passos

Integração da loja virtual

Custos e influenciadores

Eventos do site

React Native

Flutter

Instalação

Inicialização

Rastreamento de telas

Manualmente

Com React Navigation

Manualmente

Com o NavigatorObserver

Deep links e UTMs

Manualmente

Com o hook

Com o widget

Manualmente

Disparando eventos

Storage customizado

React Native

Flutter

​Instalação

​Inicialização

​Rastreamento de telas

​Manualmente

​Com React Navigation

​Manualmente

​Com o NavigatorObserver

​Deep links e UTMs

​Manualmente

​Com o hook

​Com o widget

​Manualmente

​Disparando eventos

​Storage customizado

Instalação

Inicialização

Rastreamento de telas

Manualmente

Com React Navigation

Manualmente

Com o NavigatorObserver

Deep links e UTMs

Manualmente

Com o hook

Com o widget

Manualmente

Disparando eventos

Storage customizado