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

Config	Type	Description
clientId	`string` required	This value is provided by Nuvemshop
log	`boolean` default `false`	Allows 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 />;
}

Importante: It is necessary that after sending iAmReady, the app is listening for the ACTION_NAVIGATE_SYNC action. This is because when the new admin receives the signal that the app is READY, ACTION_NAVIGATE_SYNC is sent with the initial route the app should navigate to.

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 {
  ACTION_NAVIGATE_SYNC,
  NavigateSyncResponse,
} from "@tiendanube/nexo/actions";
import { syncPathname } from "@tiendanube/nexo/helpers";
import nexo from "./nexoClient";

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

  // to send the current path of the app to the browser url
  useEffect(() => {
    const path = search ? `${pathname}${search}` : pathname;
    syncPathname(nexo, path);
  }, [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;

Important: As mentioned in the previous section, it must be ensured that this component is rendering after the iAmReady has been sent.

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

`navigateExit`

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

`navigateHeader`

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

`navigateHeaderRemove`

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

Nexo

Installation​

npm​

yarn​

Getting Started​

Create a Nexo instance​

Check if the app is connected​

Enable route synchronization​

Get Session Token​

Error handling​

Actions​

ACTION_NAVEGATE_EXIT​

ACTION_NAVIGATE_SYNC​

ACTION_NAVIGATE_GOTO​

ACTION_NAVIGATE_PATHNAME​

ACTION_AUTH_SESSION_TOKEN​

ACTION_STORE_INFO​

ACTION_NAVIGATE_GOTO_OLD_ADMIN​

ACTION_NAVIGATE_HEADER​

ACTION_DEVICE​

ACTION_LOG_ERROR​

Helpers​

connect​

iAmReady​

navigateExit​

getSessionToken​

syncPathname​

getStoreInfo​

getIsMobileDevice​

goTo​

goToOldAdmin​

copyToClipboard​

navigateHeader​

navigateHeaderRemove​

Next steps​

Installation

npm

yarn

Getting Started

Create a Nexo instance

Check if the app is connected

Enable route synchronization

Get Session Token

Error handling

Actions

`ACTION_NAVEGATE_EXIT`

`ACTION_NAVIGATE_SYNC`

`ACTION_NAVIGATE_GOTO`

`ACTION_NAVIGATE_PATHNAME`

`ACTION_AUTH_SESSION_TOKEN`

`ACTION_STORE_INFO`

`ACTION_NAVIGATE_GOTO_OLD_ADMIN`

`ACTION_NAVIGATE_HEADER`

`ACTION_DEVICE`

`ACTION_LOG_ERROR`

Helpers

`connect`

`iAmReady`

`navigateExit`

`getSessionToken`

`syncPathname`

`getStoreInfo`

`getIsMobileDevice`

`goTo`

`goToOldAdmin`

`copyToClipboard`

`navigateHeader`

`navigateHeaderRemove`

Next steps