Pular para o conteúdo principal

Nexo

O Nexo disponibiliza recursos para facilitar a comunicação entre um aplicativo externo e o administrador da Nuvemshop. Essa interação entre o Admin e o App é estabelecida através de mensagens, seguindo o padrão do observador, permitindo inscrição e desinscrição de eventos.

Essas mensagens, denominadas "Actions", são cuidadosamente definidas e associadas a "Helpers". Essas Helpers habilitam o uso das Actions como promessas, proporcionando uma abordagem eficaz e confiável para trocar informações e sincronizar operações entre as partes envolvidas.

Instalação

npm

$ npm install @tiendanube/nexo

yarn

$ yarn add @tiendanube/nexo

Começando

Criar uma instância do Nexo

ConfigTipoDescrição
clientIdstring obrigatórioEste valor é fornecido pela Nuvemshop
logboolean padrão falsePermite mostrar as mensagens transferidas entre o App e o Admin

import nexo from "@tiendanube/nexo";

const instance = nexo.create({
clientId: "123",
log: true,
});

export default instance;

Verificar se o aplicativo está conectado

Através do utilitário connect, você pode verificar se o Administrador permite a troca de mensagens e, ao mesmo tempo, com iAmReady, notificar que sua aplicação está pronta para ser exibida.

Para a aplicação React

import { useEffect, useState } from "react";
import { connect, iAmReady } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient"; // Nexo instance

function App() {
const [isConnect, setIsConnect] = useState(false);

useEffect(() => {
connect(nexo).then(() => {
setIsConnect(true);
iAmReady(nexo);
});
}, []);

if (!isConnect) return <MyAppSkeleton />;

return <MyApp />;
}

Ativar a sincronização de rotas

Essa funcionalidade permitirá que você registre a navegação do aplicativo na URL do navegador por meio de fragmentos (#myroute).

Este exemplo é feito com o React Router .

import React, { useEffect } from "react";
import { useLocation, useHistory } from "react-router-dom";
import { syncPathname } from "@tiendanube/nexo/helpers";

import nexo from "./nexoClient";
import {
ACTION_NAVIGATE_SYNC,
NavigateSyncResponse,
} from "@tiendanube/nexo/actions";

const NexoSyncRoute: React.FC<{ children: React.ReactNode }>({ children } ) => {
const { pathname } = useLocation();
const { push: goTo, replace: replaceTo } = useHistory();

//to send the current path of the app to the browser url
useEffect(() => {
syncPathname(nexo, pathname);
}, [pathname]);

//to navigate in the app if the browser url changes
useEffect(() => {
const unsuscribe = nexo.suscribe(
ACTION_NAVIGATE_SYNC,
({ path, replace }: NavigateSyncResponse) => {
replace ? goTo(path) : replaceTo(path);
}
);
return unsuscribe;
}, [goTo, replaceTo]);

return children;
}

export default NexoSyncRoute;

Obter o token de sessão

Por meio do utilitário getSessionToken, podemos obter um token de sessão (JWT) que será usado para verificar a autenticidade da solicitação ao seu Backend. O JWT é assinado com o Segredo do Cliente da Aplicação.

import axios from "axios";
import { getSessionToken } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient";

const axiosIntance = axios.create({
baseURL: "https://my-backend.com",
});

axiosIntance.interceptors.request.use(async (request) => {
const token = await getSessionToken(nexo);
const bearerToken = `Bearer ${token}`;
request.headers = { ...request.headers, Authorization: bearerToken };
return request;
});

export default axiosIntance;

Tratamento de erros

O componente ErrorBoundary permite aprimorar o tratamento de erros entre seus aplicativos e o painel de administração dos lojistas, tornando seus aplicativos mais confiáveis e proporcionando uma excelente experiência aos usuários.

Basta configurar o componente ErrorBoundary no topo da árvore de componentes do seu aplicativo. Ele será responsável por despachar automaticamente a ação ACTION_LOG_ERROR . Isso aciona a exibição de uma interface de fallback integrada ao painel de administração dos lojistas.

Essa abordagem garantirá que os erros sejam tratados de maneira eficaz, melhorando a confiabilidade de seus aplicativos e proporcionando uma experiência mais suave aos usuários. Lembre-se de que o uso do ErrorBoundary é obrigatório para publicar seu aplicativo em nossa App Store.

import React, { useEffect, useState } from "react";
import { BrowserRouter } from "react-router-dom";
import { Box, Text } from "@nimbus-ds/components";
import { ErrorBoundary, connect, iAmReady, create } from "@tiendanube/nexo";

const nexo = create({
clientId: "123",
log: true,
});

const App: React.FC = () => {
const [isConnect, setIsConnect] = useState(false);

useEffect(() => {
if (!isConnect) {
connect(nexo)
.then(async () => {
setIsConnect(true);
iAmReady(nexo);
})
.catch(() => {
setIsConnect(false);
});
}
}, []);

if (!isConnect)
return (
<Box
height="100vh"
display="flex"
justifyContent="center"
alignItems="center"
>
<Text>Conectando...</Text>
</Box>
);

return (
<ErrorBoundary nexo={nexo}>
<BrowserRouter>
<Text>Your application</Text>
</BrowserRouter>
</ErrorBoundary>
);
};

export default App;

Actions

ACTION_NAVEGATE_EXIT

Para navegar até a rota a partir da qual o aplicativo foi acessado.

Internal name:

  • app/navigate/exit;

Payload:

  • none;

Response:

  • none;

ACTION_NAVIGATE_SYNC

Para atualizar sua localização atual para propagar a navegação interna.

Internal name:

  • app/navigate/sync;

Payload:

{
pathname: string;
}

Response:

  • none;

ACTION_NAVIGATE_GOTO

Para navegar para uma rota específica no Admin.

Internal name:

  • app/navigate/goTo;

Payload:

{
pathname: string;
}

Response:

{
path: string;
replace?: boolean;
}

ACTION_NAVIGATE_PATHNAME

Para o subPathname atual, que representa o caminho do aplicativo incorporado.

Internal name:

  • app/navigate/pathname;

Payload:

  • none;

Response:

{
pathname: string;
}

ACTION_AUTH_SESSION_TOKEN

Para solicitar o token de sessão (JWT).

Internal name:

  • app/auth/sessionToken;

Payload:

  • none;

Response:

{
token: string;
}

ACTION_STORE_INFO

Para solicitar informações sobre a loja atual registrada.

Internal name:

  • app/store/info;

Payload:

  • none;

Response:

{
id: string;
name: string;
url: string;
country: string;
language: string;
currency: string;
}

ACTION_NAVIGATE_GOTO_OLD_ADMIN

Para navegar para uma rota específica localizada no antigo admin (admin/...).

Internal name:

  • app/navigate/goToOldAdmin;

Payload:

{
pathToOldAdmin: string;
}

Response:

  • none;

ACTION_NAVIGATE_HEADER

Para mostrar a ação de navegação no topo do cabeçalho.

Internal name:

  • app/navigate/header;

Payload:

{
goTo?: 'back' | string;
goToAdmin?: string;
text?: string;
remove?: boolean;
}

Response:

  • none;

ACTION_DEVICE

Para solicitar informações sobre o dispositivo móvel.

Internal name:

  • app/device;

Payload:

  • none;

Response:

{
isMobileDevice: boolean;
}

ACTION_LOG_ERROR

Permite o registro de erros, capturando informações cruciais como URL, mensagem e rastreamento (stack trace) para fins de diagnóstico.

Internal name:

  • app/log/error;

Payload:

{
url: string;
message: string;
stack: string;
}

Response:

  • none;

Helpers

connect

Aguardar se o aplicativo estiver pronto para renderizar.

Arguments:

  • nexo (NexoClient): The Nexo Instance;
  • ttl (number): Maximum time waiting for the admin, default 3000;

Response:

  • Promise<void> Success or Fail;

Example:

connect(nexo)
.then(() => {
//success
})
.catch(() => {
//fail
});

iAmReady

Para notificar que o aplicativo está sendo renderizado.

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • void

Example:

iAmReady(nexo);

Para navegar até a rota a partir da qual o aplicativo foi acessado.

Action: app/navigate/exit;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • void;

Example:

navigateExit(nexo);

getSessionToken

Para solicitar o token de sessão (JWT).

Action: app/auth/sessionToken;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • Promise<token: string>: Promise with session token;

Example:

const token = await getSessionToken(nexo);

syncPathname

Para atualizar sua localização atual para propagar a navegação interna.

Action: app/navigate/sync;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • Promise<token: string>: Promise with session token;

Example:

syncPathname(nexo, pathname);

getStoreInfo

Para solicitar informações sobre a Loja atual.

Action: app/store/info;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • Promise<StoreInfoResponse>: Promise with store info;
StoreInfoResponse {
id: string;
name: string;
url: string;
country: string;
language: string;
currency: string;
}

Example:

const storeInfo = await getStoreInfo(nexo);

getIsMobileDevice

Para verificar se o aplicativo está sendo carregado do dispositivo móvel.

Action: app/device;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • Promise<boolean>: True / False;

Example:

const isMobileDevice = await getIsMobileDevice(nexo);

goTo

Para navegar para uma rota específica no Admin.

Action: app/navigate/goTo;

Arguments:

  • nexo (NexoClient): The Nexo Instance;
  • path (string): Specific path to navigate;

Response:

  • void;

Example:

goTo(nexo, "/products");

goToOldAdmin

Para navegar para uma rota específica no Old Admin, apenas está disponível o modo Web (dispositivo não móvel).

Action: app/navigate/goToOldAdmin;

Arguments:

  • nexo (NexoClient): The Nexo Instance;
  • path (string): Specific path to navigate;

Response:

  • void;

Example:

goToOldAdmin(nexo, "/products");

copyToClipboard

Para copiar o texto enviado para a área de transferência do dispositivo.

Action: app/utils/copyToClipboard;

Arguments:

  • nexo (NexoClient): The Nexo Instance;
  • text (string): Text to copy;

Response:

  • Promise<boolean>: If copied successfully;

Example:

copyToClipboard(nexo, "text to copy");

Para mostrar a ação de navegação no cabeçalho superior, apenas está disponível o modo Web (dispositivo não móvel).

Action: app/utils/copyToClipboard;

Arguments:

  • nexo (NexoClient): The Nexo Instance;
  • config (NavigateHeaderRequest): Config to navegate header;
 NavigateHeaderRequest {
goTo: "back" | string;
text: string;
};

Response:

  • void;

Example:

navigateHeader(nexo, { goTo: "/", text: "Product List" });
//or
navigateHeader(nexo, { goTo: "back", text: "Back" });

Remove a ação do Header Top, disponível apenas no modo Web (dispositivos não móveis).

Action: app/utils/copyToClipboard;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • void;

Example:

navigateHeaderRemove(nexo);

Próximos passos

  • Saiba mais sobre nossa API