@typecastdev/react-lib v0.1.0-2

Typecast react-lib

Typecast React module, add customer experience flags to your React App.

Latest Version: v0.1.1

Peer dependencies:

Note: the ^ symbol before a peer dependency indicates we support that version of the package and above.

• react: ^17.0.2
• react-dom: ^17.0.2

Support and Maintenance

Please do not hesitate to send us an email with any questions/concerns/problems.

Maintainers:

• Faiz - faiz@typecast.dev
• Srdjan - srdjan@typecast.dev

Meta

Note: Please install stable versions, if you would like to test a pre-release version please email one of the Maintainers.

Stable Versions:

Setup Tutorial

Note: if you don't already have an https://www.npmjs.com/ account, please create one here, our package is private.

1. Accept the invite sent to your email to join the @typecastdev npm organization.

2. Ensure that you can see the @typecastdev/react-lib package. Accessible through this link.

3. In your command line, ensure you are signed in to npm by running the command npm login.

Here's a snippet of what you can expect to see. You'll have to fill out the prompts Username, Password, Email and Enter one-time password.

$ npm login
npm notice Log in on https://registry.npmjs.org/
Username: typecastfaiz
Password: 
Email: (this IS public) faiz@typecast.dev
npm notice Please check your email for a one-time password (OTP)
Enter one-time password: ########
Logged in as typecastfaiz on https://registry.npmjs.org/.

4. Install the @typecastdev/react-lib package using your preferred package manager.

For installation help please take a look at our Installation section.

5. Once you've installed the package, make sure you should see the following in your package.json

  "name": "web-app",
  "version": "0.1.0",
  "dependencies": {
    ...
    "@typecastdev/react-lib": "^0.1.1",
    ...
  },
  ...
}

6. Import Typecast from @typecastdev/react-lib by writing this import statement somewhere in your code:

import * as Typecast from '@typecastdev/react-lib';

Awesome! You now should have access to all our functions/components.

Ex: Typecast.TypecastFlag.

Read more about our API here

7. Using Typecast: please head over to our Usage section to learn how to create your first UX Flag!

Usage

Note: for API reference please check our API section.

Creating your first UX Flag

1. Import Typecast into your codebase. Normally Typecast will need to be imported wherever you use anything from our API

import * as Typecast from '@typecastdev/react-lib';

2. Initialize Typecast with the initializeTypecast function.

This method is required to be called for any of your TypecastFlag components to function properly. If this method is not called, is called incorrectly, or fails, the TypecastFlag components will simply default to rendering the children passed to them (in other words, they won't exist.).

Prerequisites:

Get your orgId from app.typecast.dev.

The ID should look something like b2c6c838-f2bd-464c-b8a0-e0e90bc7eb3b

Ensure you have an End User created in the End users tab.

Once you've created an end user, you can create a customization for them.

Create a customization for your End User in the Customizations tab.

You'll need to have some info:

Name: Required, Unique - the name of your customization, this will link directly to your TypecastFlag component's name prop.

Action: Required - the action that this customization executes.

Expression: Required - a boolean expression for your customization, ex: user_type=="manager" would only trigger this customization for an End User that has Customer Data:

{
    user_type: "manager"
}

Create some Customer data for your created end users.

First: select the end user from the input dropdown.

Then: enter a payload for the data.

Note: the payload for the Customer data must be valid JSON.

Examples:

{
    user_type: "manager"
}

{
    age: 30
}

{
    isEmployed: true
}

This data is what the Customizations you create will parse when determining whether or whether not to send a customization for a given user to the SDK.

Now we are ready to initializeTypecast.

Find a useEffect or appropriate spot to call initializeTypecast (normally recommended to be implemented near where you make other API calls).

initializeTypecast will make a call to our API and retrieve evaluations for your app based on your orgId and the userId you specified. This function only needs to be called once.

It is recommended to place this initializeTypecast call earlier in your web-app (i.e. a Dashboard.js or a Home.js page). This way you can ensure that evaluations load before your end users encounter their first TypecastFlag components.

Example: In our Dashboard.js:

Note that in this case we are hard coding our userId to "bailey". But this can be anything, as long as you create a corresponding End User with the correct userId.

Handler note: you can also add an optional onTypecastInitialized handler in the second parameter of the initializeTypecast method.

const DashboardPage = () => {
  const handleTypecastInitializedOptionalHandler = (response) => {
    console.log(response)
  }

  useEffect(() => {
    // It is not required to wait for this call to finish.
    Typecast.initializeTypecast({
      orgId: "b2c6c838-f2bd-464c-b8a0-e0e90bc7eb3b",
      userId: "bailey"
    }, handleTypecastLoadedOptionalHandler);
  });
  ...
}

Now that we have our initializeTypecast function called, we can begin to add TypecastFlag components to our code.

For your app's safety initializeTypecast will abort after 3.7s of request time. If this method aborts, no TypecastFlag will enable across the app. If you are having trouble, please contact our Maintainers.

Note that you can check if the initialize function is working by checking the Network tab on your browser on the page you called initializeTypecast and looking for a call to evaluate. It should be have a status of 200.

3. Add a TypecastFlag to your component.

In this case we want to hide some content from our end user bailey (in previous steps we would have created a customization with name: hideFromBailey with action: hide).

Note: TypecastFlag components will wait up to 500ms for evaluations to be loaded, if it is the case that the evaluations did load from the initializeTypecast function, the appropriate actions will be effected. If there is an issue with initializeTypecast or the function is not called, TypecastFlag will default to rendering the children that it has wrapped.

Loading note: For the duration of time that the TypecastFlag is waiting for evaluations to be loaded (up to 500ms), a Skeleton loader will appear for the end user.

Right now this is what our code looks like:

import * as React from "react";
import { Card, CardContent, CardHeader } from '@mui/material';

import * as Typecast from '@typecastdev/react-lib';

const DashboardPage = () => {
  useEffect(() => {
    Typecast.initializeTypecast({
      orgId: "b2c6c838-f2bd-464c-b8a0-e0e90bc7eb3b",
      userId: "bailey"
    });
  });


  return (
    <Card>
      <CardHeader title="Welcome to Typecast" />
        <CardContent>Something bailey shouldn't see</CardContent>
    </Card>
  )
}

export default DashboardPage;

Adding a TypecastFlag is as simple as wrapping the content that we want to conditionally render with our component.

return (
    <Card>
      <CardHeader title="Welcome to Typecast" />
      <Typecast.TypecastFlag name="hideFromBailey">
        <CardContent>Something bailey shouldn't see</CardContent>
      </Typecast.TypecastFlag>
    </Card>
  )

Ensure that you do not forget the name prop for the component, and make sure you have a corresponding Customization in your app.typecast.dev instance.

And that's all! Now you can create as many TypecastFlag components as you'd like in your codebase!

4. Congrats! We've successfully created our first UX Flag!

A view of our Dashboard.js component.

import * as React from "react";
import { Card, CardContent, CardHeader } from '@mui/material';

import * as Typecast from '@typecastdev/react-lib';

const DashboardPage = () => {
  useEffect(() => {
    Typecast.initializeTypecast({
      orgId: "b2c6c838-f2bd-464c-b8a0-e0e90bc7eb3b",
      userId: "bailey"
    });
  });


  return (
    <Card>
      <CardHeader title="Welcome to Typecast" />
      <Typecast.TypecastFlag name="oranges">
        <CardContent>Something bailey shouldn't see</CardContent>
      </Typecast.TypecastFlag>
    </Card>
  )
}

export default DashboardPage;

Installation

In the root folder of your app run one of the following commands to install @typecastdev/react-lib, depending on the package manager you use.

Note that if you do not use versions of packages listed in our Peer dependencies list, you may have trouble installing our package. Please contact our Maintainers

Using npm

    npm install @typecastdev/react-lib

Using yarn

    yarn add @typecastdev/react-lib

Using pnpm

    pnpm install @typecastdev/react-lib

API

Typecast package exposed functions/components.

You can import Typecast by writing the following code somewhere in your codebase:

import * as Typecast from '@typecastdev/react-lib';

Component TypecastFlag

• TypecastFlag component used to create custom UX Flags accessible from app.typecast.dev.

TypecastFlag: React.Component<TypecastFlagProps, TypecastFlagState>;

/**
 * TypecastFlag props.
 */
interface TypecastFlagProps {
    /**
     * TypecastFlag name, found in `app.typecast.dev`.
     */
    name: string;
}

Function initializeTypecast

• Initializes Typecast configurations for an app based on orgId and userId.
• Customizations are available from app.typecast.dev
• @param params: initializeTypecast parameter object, contains: orgId, userId, url?, and verbose?
• @param onTypecastInitialized: (Optional) Handler function parameter, called when Typecast is loaded.

initializeTypecast: (params: InitializeTypecastParams, onTypecastInitialized?: (response: OnTypecastInitializedParams) => any) => Promise<boolean>;


/**
 * `initializeTypecast` function parameters.
 */
interface InitializeTypecastParams {
    /**
     * Organization Id, can be found in `app.typecast.dev`.
     */
    orgId: string,
    /**
     * Id of the current logged in user, should be aligned with userId from `app.typecast.dev`
     */
    userId: string,
    /**
     * (Optional) Specific page url.
     */
    url?: string;
    /**
     * (Optional) Verbose logging, includes `warn` and `info` logs.
     */
    verbose?: boolean;
}

/**
 * Optional parameters for `initializeTypecast` handler function. 
 */
interface OnTypecastInitializedParams {
    /**
     * (Optional) Status of `intializeTypecast`, false if failed to initialize or aborted.
     */
    status?: boolean,
    /**
     * (Optional) List of evaluations retrieved for the given parameters.
     */
    evaluations?: Array<TypecastEvaluation>
}