Nexo
Nexo proporciona recursos para facilitar la comunicación entre una aplicación externa y el administrador de Tiendanube. Esta interacción entre el administrador y la aplicación se establece mediante mensajes, siguiendo el patrón de observador, lo que permite la suscripción y cancelación de eventos.
Estos mensajes, llamados "Actions", están cuidadosamente definidos y asociados con "Helpers". Estos Helpers permiten que las Actions se utilicen como promesas, lo que proporciona un enfoque eficaz y confiable para intercambiar información y sincronizar operaciones entre las partes involucradas.
Instalación
npm
$ npm install @tiendanube/nexo
yarn
$ yarn add @tiendanube/nexo
Empezando
Crear una instancia de Nexo
Config | Tipo | Descripción |
---|---|---|
clientId | string requerido | Este valor es proporcionado por Tiendanube |
log | boolean por defecto false | Permite mostrar las transferencias de mensajes entre la Aplicación y el Administrador |
import nexo from "@tiendanube/nexo";
const instance = nexo.create({
clientId: "123",
log: true,
});
export default instance;
Comprobar si la aplicación está conectada
A través del utilitario connect
puedes verificar si el Administrador permite el intercambio de mensajes y al mismo tiempo, con iAmReady
, notificar que tu aplicación está lista para mostrarse.
Para la aplicación 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 />;
}
Habilitar la sincronización de rutas
Esta funcionalidad te permitirá registrar la navegación de la aplicación en la URL del navegador a través de fragmentos (#myroute).
Este ejemplo está hecho con 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;
Obtener el token de sesión
A través del utilitario getSessionToken
, podemos obtener un token de sesión (JWT) que se utilizará para verificar la autenticidad de la solicitud a tu Backend. El JWT está firmado con el Cliente Secreto de la Aplicación.
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;
Manejo de errores
El componente ErrorBoundary
permite mejorar el manejo de errores entre sus aplicaciones y el panel de administración de los comerciantes, lo que hace que sus aplicaciones sean más confiables y brinden una excelente experiencia a los usuarios.
Simplemente configure el componente ErrorBoundary
en la parte superior del árbol de componentes de su aplicación. Será responsable de despachar automáticamente la acción ACTION_LOG_ERROR
. Esto activa la visualización de una interfaz de respaldo integrada en el panel de administración de los comerciantes.
Este enfoque asegurará que los errores se manejen de manera efectiva, mejorando la confiabilidad de sus aplicaciones y brindando una experiencia más fluida a los usuarios. Recuerde que el uso de ErrorBoundary
es obligatorio para publicar su aplicación en nuestra tienda de aplicaciones.
Actions
ACTION_NAVEGATE_EXIT
Navegar hasta la ruta desde la que se accedió a la aplicación.
Internal name:
app/navigate/exit
;
Payload:
none
;
Response:
none
;
ACTION_NAVIGATE_SYNC
Actualizar su ubicación actual para propagar la navegación interna.
Internal name:
app/navigate/sync
;
Payload:
{
pathname: string;
}
Response:
none
;
ACTION_NAVIGATE_GOTO
Para navegar a una ruta específica en Admin.
Internal name:
app/navigate/goTo
;
Payload:
{
pathname: string;
}
Response:
{
path: string;
replace?: boolean;
}
ACTION_NAVIGATE_PATHNAME
Al subPathname actual, que representa la ruta de la aplicación integrada.
Internal name:
app/navigate/pathname
;
Payload:
none
;
Response:
{
pathname: string;
}
ACTION_AUTH_SESSION_TOKEN
Para solicitar el token de sesión (JWT).
Internal name:
app/auth/sessionToken
;
Payload:
none
;
Response:
{
token: string;
}
ACTION_STORE_INFO
Para solicitar información sobre la tienda actual 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 a una ruta específica ubicada en el antiguo administrador (admin/...).
Internal name:
app/navigate/goToOldAdmin
;
Payload:
{
pathToOldAdmin: string;
}
Response:
none
;
ACTION_NAVIGATE_HEADER
Para mostrar la acción de navegación en el encabezado superior.
Internal name:
app/navigate/header
;
Payload:
{
goTo?: 'back' | string;
goToAdmin?: string;
text?: string;
remove?: boolean;
}
Response:
none
;
ACTION_DEVICE
Para solicitar información sobre si dispositivo móvil.
Internal name:
app/device
;
Payload:
none
;
Response:
{
isMobileDevice: boolean;
}
ACTION_LOG_ERROR
Permite el registro de errores, capturando información crucial como la URL, el mensaje y la traza de pila (stack trace) con fines de diagnóstico.
Internal name:
app/log/error
;
Payload:
{
url: string;
message: string;
stack: string;
}
Helpers
connect
Esperar si la aplicación está lista para procesarse.
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 la aplicación se está procesando.
Arguments:
nexo (NexoClient)
: The Nexo Instance;
Response:
void
Example:
iAmReady(nexo);
navigateExit
Navegar hasta la ruta desde la que se accedió a la aplicación.
Action: app/navigate/exit
;
Arguments:
nexo (NexoClient)
: The Nexo Instance;
Response:
void
;
Example:
navigateExit(nexo);
getSessionToken
Para solicitar el token de sesión (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
Actualizar su ubicación actual para propagar la navegación 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 información sobre la Tienda actual.
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 si la aplicación se está cargando desde el dispositivo móvil.
Action: app/device
;
Arguments:
nexo (NexoClient)
: The Nexo Instance;
Response:
Promise<boolean>
: True / False;
Example:
const isMobileDevice = await getIsMobileDevice(nexo);
goTo
Para navegar a una ruta específica en 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 a una ruta específica en Old Admin, solo está disponible el modo web (no para dispositivos móviles).
Action: app/navigate/goToOldAdmin
;
Arguments:
nexo (NexoClient)
: The Nexo Instance;path (string)
: Specific path to navigate;
Response:
void
;
Example:
goToOldAdmin(nexo, "/products");
copyToClipboard
Copiar el texto enviado al portapapeles del 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");
navigateHeader
Para mostrar la acción de navegación en el encabezado superior, solo está disponible el modo web (no para dispositivos móviles).
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" });
navigateHeaderRemove
Elimina la acción de Header Top, disponible solo en modo Web (dispositivos no móviles).
Action: app/utils/copyToClipboard
;
Arguments:
nexo (NexoClient)
: The Nexo Instance;
Response:
void
;
Example:
navigateHeaderRemove(nexo);
Próximos pasos
- Obtenga más información sobre nuestra API