Skip to main content

Nexo

Nexo provides resources to facilitate communication between an external application and the Nuvemshop administrator. This interaction between the admin and the app is established through messages, following the observer pattern, allowing for event subscription and unsubscription.

These messages, called "Actions," are carefully defined and associated with "Helpers." These Helpers enable the use of Actions as promises, providing an effective and reliable approach to exchange information and synchronize operations between the involved parties.

Installation

npm

$ npm install @tiendanube/nexo

yarn

$ yarn add @tiendanube/nexo

Getting Started

Create a Nexo instance

ConfigTypeDescription
clientIdstring requiredThis value is provided by Nuvemshop
logboolean default falseAllows to show the message transfers between the App and the Admin

import nexo from "@tiendanube/nexo";

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

export default instance;

Check if the app is connected

Through the connect util you can check if the Admin allows you to exchange messages and at the same time with iAmReady notify that your application is ready to show.

To react application

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 />;
}

Enable route synchronization

This functionality will allow you to record the app navigation of your app in the browser URL via fragment (#myroute)

This example is made with 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;

Get Session Token

Through the getSessionToken util we can obtain a session token (JWT) that will be used to verify the authenticity of the request to your Backend. The JWT is signed with the Application's Client Secret

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;

Error handling

The ErrorBoundary component allows you to improve error handling between your applications and the merchants' administration panel, making your applications more reliable and providing an excellent user experience.

Simply configure the ErrorBoundary component at the top of your application's component tree. It will be responsible for automatically dispatching the action ACTION_LOG_ERROR . This triggers the display of a fallback interface integrated into the merchants' admin panel.

This approach will ensure that errors are handled effectively, improving the reliability of your applications and providing a smoother experience for your users. Please remember that using ErrorBoundary is mandatory to publish your app on our 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

To navigate to the route from which the application was accessed.

Internal name:

  • app/navigate/exit;

Payload:

  • none;

Response:

  • none;

ACTION_NAVIGATE_SYNC

To update his current location to propagate the internal navigation.

Internal name:

  • app/navigate/sync;

Payload:

{
pathname: string;
}

Response:

  • none;

ACTION_NAVIGATE_GOTO

To navigate to a specific route in Admin.

Internal name:

  • app/navigate/goTo;

Payload:

{
pathname: string;
}

Response:

{
path: string;
replace?: boolean;
}

ACTION_NAVIGATE_PATHNAME

To current subPathname, which represents the path of the embedded app.

Internal name:

  • app/navigate/pathname;

Payload:

  • none;

Response:

{
pathname: string;
}

ACTION_AUTH_SESSION_TOKEN

To requests the session token (JWT).

Internal name:

  • app/auth/sessionToken;

Payload:

  • none;

Response:

{
token: string;
}

ACTION_STORE_INFO

To request information about current Store logged.

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

To navigate to a specific route located in the old admin (admin/...).

Internal name:

  • app/navigate/goToOldAdmin;

Payload:

{
pathToOldAdmin: string;
}

Response:

  • none;

ACTION_NAVIGATE_HEADER

To show the navigation action in the Header Top.

Internal name:

  • app/navigate/header;

Payload:

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

Response:

  • none;

ACTION_DEVICE

To requests information about if mobile device.

Internal name:

  • app/device;

Payload:

  • none;

Response:

{
isMobileDevice: boolean;
}

ACTION_LOG_ERROR

Allows error logging, capturing crucial information such as URL, message and stack trace for diagnostic purposes.

Internal name:

  • app/log/error;

Payload:

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

Helpers

connect

To wait if the application is ready to render.

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

To notify that the app is rendering.

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • void

Example:

iAmReady(nexo);

To navigate to the route from which the application was accessed.

Action: app/navigate/exit;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • void;

Example:

navigateExit(nexo);

getSessionToken

To requests the session token (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

To update his current location to propagate the internal navigation.

Action: app/navigate/sync;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

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

Example:

syncPathname(nexo, pathname);

getStoreInfo

To request information about current Store.

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

To check if the app is being loaded from the Mobile Device.

Action: app/device;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • Promise<boolean>: True / False;

Example:

const isMobileDevice = await getIsMobileDevice(nexo);

goTo

To navigate to a specific route in Admin.

Action: app/navigate/goTo;

Arguments:

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

Response:

  • void;

Example:

goTo(nexo, "/products");

goToOldAdmin

To navigate to a specific route in Old Admin, only available Web mode (non mobile device).

Action: app/navigate/goToOldAdmin;

Arguments:

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

Response:

  • void;

Example:

goToOldAdmin(nexo, "/products");

copyToClipboard

To copy the sent text to the device's clipboard.

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");

To show the navigation action in the Header Top, only available Web mode (non mobile device).

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" });

Removes the action of Header Top, available only in Web mode (non-mobile devices).

Action: app/utils/copyToClipboard;

Arguments:

  • nexo (NexoClient): The Nexo Instance;

Response:

  • void;

Example:

navigateHeaderRemove(nexo);

Next steps

  • Learn more about our API