@open-web/react-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.1 • Public • Published

    OpenWeb React SDK

    npm version CircleCI codecov

    The OpenWeb React SDK package enables OpenWeb products to be added to React single-page applications. Through this package, an OpenWeb product is exported as a wrapped React component that is responsible for initializing shared cross-product functionalities and booting specific OpenWeb products.

    Requirements

    Installation

    yarn add @open-web/react-sdk
    # or
    npm install @open-web/react-sdk

    Usage

    Conversation Implementation

    Conversation enables you to create a fluent conversation experience that fuels quality interactions with community and content and allows users to create valuable and engaging content.

    Separated Product Implementation

    Use the following steps to add a single Conversation to a single-page application:

    1. Import Conversation from the OpenWeb React SDK and add a Conversation instance to the single-page application.
    import { Conversation } from '@open-web/react-sdk';
    
    const CommentsSection = () => {
      return (
        <Conversation
          spotId="sp_example"
          postId="example_post"
          articleTags={['tag1', 'tag2', 'tag3']}
          postUrl="http://www.example.com"
        />
      );
    };
    1. Define the Conversation props:
      • spotId
      • postId
      • articleTags
      • postUrl

    OpenWebProvider Implementation

    It is highly recommended to use our OpenWebProvider implementation as it allows you to pass spotId only once in addition to more functionalities that being added on top of our products.

    💡 NOTE: In case you are using OpenWebProvider, please make sure all OpenWeb products are being rendered within it.

    1. Import OpenWebProvider and Conversation from the OpenWeb React SDK and wrap the entire application – including each Conversation instance – with OpenWebProvider. The OpenWebProvider component allows you to define spotId one time for all Conversation instances within the app.
    import { OpenWebProvider, Conversation } from '@open-web/react-sdk';
    
    const App = () => {
      return (
        <OpenWebProvider spotId="sp_example">
          <Conversation postId="example_post" articleTags={['tag1', 'tag2', 'tag3']} postUrl="http://www.example.com" />
          ...
          <Conversation postId="example_post2" articleTags={['tag1', 'tag2', 'tag3']} postUrl="http://www.example2.com" />
        </OpenWebProvider>
      );
    };
    1. Define the spotId prop of OpenWebProvider.
    2. Define the props for each Conversation:
      • postId
      • articleTags
      • postUrl

    💡 NOTE: If you prefer not to wrap your app with the OpenWebProvider component, use the Single Conversation implementation instructions and add multiple Conversation instances to the single-page application.

    Messages Count Implementation

    To show your users the engagement level of a specific Conversation, you can use the MessagesCount component to display the number of user comments that have been posted to the Conversation.

    You can style the text returned from the component by defining the className attribute with the name of CSS class or by defining an inline style.

    💡 NOTE: The MessagesCount component does not need to be displayed with the Conversation it references. For example, you can preview an article with its title and number of posted comments.

    1. Import MessagesCount from the OpenWeb React SDK.
    import { MessagesCount } from '@open-web/react-sdk';
    
    const App = () => {
      return <MessagesCount spotId="sp_example" postId="example_post" className="yourClassName" />;
    };
    1. Define the attributes of MessagesCount:
      • spotId
      • postId
      • (optional) className

    Two Token Authentication

    To use TTH add the authentication property to the OpenWebProvider. authentication object holds the current user ID who is logged into the partner and the callback the performs BED to BED handshake with OpenWeb as follows:

    • userId <string | undefined>: A unique string that is stored as an internal state for OW's login system (client). The id let us know whether current user has changed and we need to perform login again. When userId=undefined the provider performs a logout.
    • performBEDHandshakeCallback <(codeA: string) => Promise<string>>: A callback that recives Token A pass it to partner's BED. After the partner's performs the login with OW it sends back Token B (code_b) and returns that to OW's client.
    • onUserChanged? <(user: User) => void: A callback that is invoked on current user change. User holds the current user details.
    • onError? <(err: Error) => void: A callback that is invoked on error occurred.
    //...
       <OpenWebProvider spotId="<SPOT_ID>" authentication={{
          userId: 'test-user-unique-id or undefined when user is logged out'
          performBEDHandshakeCallback: (codeA) => {console.log("see below implementation proposal for more details")}
          onUserChanged={(user) => {console.log("Current User in OW is -", user)}}
          onError={(err) => {console.log("Oh NO! something wrong happened -", err)}}
        }}>
    //...

    Start Two Token Handshake manually

    To start the TTH one should call startTTH function with:

    • userId <string>: A unique string that is stored as an internal state for OW's login system (client). The id let us know whether current user has changed and we need to perform login again.
    • performBEDHandshakeCallback <(codeA: string) => Promise<string>>: A callback that recives Token A pass it to partner's BED. After the partner's performs the login with OW it sends back Token B (code_b) and returns that to OW's client.
    import { startTTH } from '@open-web/react-sdk';
    
    const login = () => {
      startTTH({ userId, performBEDHandshakeCallback });
    };
    
    // An example for the performBEDHandshakeCallback callback function
    const performBEDHandshakeCallback = async (codeA: string) => {
      const { code_b: codeB } = await fetch(`https://opeweb.partner.example/start-handshake`, {
        method: 'POST',
        body: JSON.stringify({
          // codeA that the callback gets and should be passed to OW's BED
          code_a: codeA,
          // We want to let the BED we want to login with a certain user - that is, the user we should do the BED handshake with OW.
          userId,
        }),
      }).then(function (res) {
        return res.json();
      });
    
      // codeB has been received from OW's BED and it is returned to OW's client to complete the handshake.
      return codeB;
    };

    Logout manually

    To perform a logout, one should call the logout function.

    import { logout } from '@open-web/react-sdk';
    
    const logoutFromOw = () => {
      logout();
    };

    Tracking OpenWeb's Custom Events

    OpenWeb provides multiple custom events indicates when a particular event occurred. It can be useful in tracking engagement or for triggering unrelated functionality outside of OpenWeb's products.

    List of all of our events can be found here: https://developers.openweb.com/docs/event-listener-reference

    Usage

    Tracking events can be enabled only when using OpenWebProvider implementation, by passing tracking as prop to OpenWebProvider component.

    The tracking prop is an object mapping between event-name (listed here) to handler function. Each function will be triggered when the event is dispatched by any of OpenWeb's products. The custom event is passed to the function as its only argument.

    In case the event has any associated payload to it, it can be accessed by referencing to event.detail.payload.

    import { OpenWebProvider } from '@open-web/react-sdk';
    
    const App = () => {
      return (
        <OpenWebProvider
          spotId={'sp_example'}
          tracking={{
            ['event-name']: event => {
              console.log('Do Something with this event!', event);
            },
          }}
        ></OpenWebProvider>
      );
    };

    OpenWeb Widgets

    Popular in The Community

    https://developers.openweb.com/docs/popular-in-the-community

    import { PopularInTheCommunity } from '@open-web/react-sdk';
    
    <PopularInTheCommunity postId={postId} postUrl={postUrl} />;

    Optional attributes:

      isSidebar?: boolean;
      categories?: string[];

    Spotlight

    https://developers.openweb.com/docs/community-spotlight

    import { Spotlight } from '@open-web/react-sdk';
    
    <Spotlight />;

    Optional attributes:

      isSidebar?: boolean;
      cardType?: 'counter' | 'form';

    Reactions

    https://developers.openweb.com/docs/reactions

    import { Reactions } from '@open-web/react-sdk';
    
    <Reactions postId={postId} postUrl={postUrl} />;

    Optional attributes:

      isSidebar?: boolean;

    Topic Tracker

    https://developers.openweb.com/docs/topic-tracker

    import { Reactions } from '@open-web/react-sdk';
    
    <TopicTracker postId={postId} postUrl={postUrl} />;

    Optional attributes:

      isSidebar?: boolean;
      keywords?: string[];
      authors?: string[];

    Install

    npm i @open-web/react-sdk

    DownloadsWeekly Downloads

    311

    Version

    1.4.1

    License

    UNLICENSED

    Unpacked Size

    113 kB

    Total Files

    42

    Last publish

    Collaborators

    • alexander.p
    • spotim_admin
    • dortzur
    • daniel.k