Dimply SDK for react-native

Installing

You will have received a token to use to access the private npm repository for the SDK packages

if you are using npm

npm config set '//registry.npmjs.org/:_authToken' "${NPM_TOKEN}"
NPM_TOKEN=xxx npm install @dimply-sdk/react-native

if you are using yarn add this to your .yarnrc.yml file (or equivalent)

npmScopes:
  "dimply-sdk":
    npmAuthToken: { $NPM_TOKEN }

and running NPM_TOKEN=xxx yarn i @dimply-sdk/react-native

Adding to your react-native application

1. Add <DimplySDK></DimplySDK> around your application with a root configuration.

import { DimplySDK } from "@dimply-sdk/react-native";

const App = () => {
  return (
    <DimplySDK
      config={{
        baseURI: "https://app.development.dimply.ai",
        organizationSlug: "default_organization",
        authenticationConfiguration: {
          type: "jwt",
          value: "...",
        },
        DefaultLoadingComponent: () => <div>Loading...</div>,
        DefaultErrorComponent: ({ reason }) => <div>Something's wrong...</div>,
      }}
    >
      ... your app
    </DimplySDK>
  );
};

2. Configure your journey index page with some journey collections by adding at least one <DimplySDK.Section> to render a section to show journeys matching the configuration provided.

  import { DimplySDK } from "@dimply-sdk/react-native";

  const collectionConfiguration: CollectionConfiguration = {
      type: "collection-configuration",
      onlyTags: {["business", "family"]},
      onlyRecommended: true,
      layoutConfiguration: {
        type: "layout-configuration",
        xs: {
          containerType: "VerticalList",
          tileType: "TileStandardLeft",
          themeContext: "blue",
        },
        sm: {
          containerType: "HorizontalScroll",
          tileType: "TileStandardTop",
          themeContext: "blue",
        },
      },
  };

  const Dashboard = () => {
    return (
      <View>
        <MyDashboardComponent />
        <DimplySDK.Section
          collection={collectionConfiguration}
        />
        <MyOtherDashboardComponent />
        <DimplySDK.Section ... />
      </View>
    );
  };

3. Configure a way for the SDK to display a journey. We support 2 methods

a. As a container without routing such as a modal

add <DimplySDK.RootPortal /> high up in your application tree, but inside <DimplySDK />

import { DimplySDK } from "@dimply-sdk/react-native";

const App = () => {
  return (
    <DimplySDK>
      ... your app
      <DimplySDK.RootPortal ContainerComponent={MyModal} />
    </DimplySDK>
  );
};

b. by routing to a new page in your application such as /journey/uuid

Create a routable page in your application with the chrome required, and add a <DimplySDK.Journey /> component with the id passed in. You will need to provide a custom navigation handler to the component to route to the correct page

import { DimplySDK, handleNavigationTargets } from "@dimply-sdk/react-native";

const JourneyPage = () => {
  const { id } = useParams();
  const navigationHandler = handleNavigationTargets({
    journey: (id) => nav(`/journey/${id}`),
    other: () => nav(`/dashboard`),
  });

  return (
    <div>
      My page content
      <DimplySDK.Journey id={id} navigationHandler={navigationHandler} />
    </div>
  );
};

and on the page containing a section, ensure a navigationHandler is provided on your collection config

import { DimplySDK, handleNavigationTargets } from "@dimply-sdk/react-native";

const Index = () => {
  const navigationHandler = handleNavigationTargets({
    journey: (id) => nav(`/journey/${id}`),
    other: () => nav(`/dashboard`),
  });

  return (
    <div>
      <DimplySDK.Section
        collection={{
          type: "collection-configuration",
          onlyTags={["business", "family"]}
          onlyRecommended: true,
          layoutConfiguration: ...
          navigationHandler,
        }}
      />
    </div>
  );
};

Configuration options

DimplySDK

config

import { type DimplySDKConfigInterface } from "@dimply-sdk/react-native";

authenticationConfiguration

Signed JWT

You should inject the value from a recently generated and signed JWT with a stable 'sub' key that identifies the user.

{
  type: "jwt",
  value: "...",
}

baseURI

The API you will talk to (provided by Dimply)

organizationSlug

The identifier for your organization (provided by Dimply)

DefaultLoadingComponent

A react component that is rendered when anything is loading. Should fill its relatively positioned container

DefaultErrorComponent

A react component that is rendered when an error occurs.Should fill its relatively positioned container

breakpointConfiguration

Alternate breakpoint definitions if your theme deviates from the defaults

{
  xs: 0,
  sm: 600,
  md: 960,
  lg: 1280,
}

DimplySDK.Section

import { type DimplySDKSectionInterface } from "@dimply-sdk/react-native";

overrideViewport

By default the space taken by the widget is automatic based on the containerType / tileType combiniation. You can however pass override responsive styles to the viewport configuration. Allowed sizes are xs, sm, md, lg. Most css styles are supported here, camelCased.

{
  type: "viewport-configuration",
  xs: {
    height: "150px", // height of frame to show
    width: "100%", // width of frame to show
  },
  sm: {
    height: "200px",
    width: "90%",
  },
}

```js
{
  type: "viewport-configuration",
  xs: {
    height: "150px", // height of frame to show
    width: "100%", // width of frame to show
  },
}

layoutConfiguration

Configure how the collection will be rendered on a per-breakpoint basis

import { type ResponsiveLayoutConfiguration } from "@dimply-sdk/react-native";

{
  type: "layout-configuration",
  xs: {
  {
    tileType: "TileStandardTop", // what kind of tile to show
    containerType: "HorizontalScroll", // how to contain the tiles
    themeContext: "pink",
  },
  sm: { ... }
}

collection

{
  type: "collection-configuration",
  onlyTags: ["tag-name"], // optional
  showCompleted: true; // optional, default true (completed journeys appear at end)
  onlyRecommended: true; // optional, default based on whether onlyTags is set.
  LoadingComponent: <LoadingScreen />, // optional to show while we are loading and authenticating
  layoutConfiguration: ...
}