pwa-channels-sdk

PWA Channels SDK

pwa-channels-sdk

An sdk built to incorporate all the Tata channels according to user interests which gives the user conversational overview of different Tata products and offerings. Can be used as a plug-n-play library into the main application.

Installation

npm install @tata-digital/pwa-channels-sdk

Also, if you are not already using react-router-dom in your project, then install it since it's required to run the SDK.

npm install react-router-dom

Upgrade

If your application already has a (possibly outdated) installed version of @tata-digital/pwa-channels-sdk, then you can upgrade it to the latest version of @tata-digital/pwa-channels-sdk using the following command.

npm install @tata-digital/pwa-channels-sdk@latest

Integration Steps

• Wrap your application's root App component inside ChannelsProvider component exposed from @tata-digital/pwa-channels-sdk package and pass the config as a prop to the ChannelsProvider component.

import { ChannelsProvider } from '@tata-digital/pwa-channels-sdk'
import '@tata-digital/pwa-channels-sdk/dist/index.css'

const config = {
  mode: 'dev',   // dev, prod
  apiBaseUrl: 'https://dapi.tatadigital.com/channelssdkdev'
}

<ChannelsProvider config={config}>
  <App />
</ChannelsProvider>

The above config object is the minimum configuration required to get started. The apiBaseUrl property of the config object is the base url of the Channels SDK API endpoint. Other optional attributes of the config object will be discussed later in this document.

Make sure that you also import the style file as shown above so that Channels components are rendered correctly.

Also, please make sure that the ChannelsProvider is wrapped inside BrowserRouter provided by react-router-dom.

<BrowserRouter>
  <ChannelsProvider config={config}>
    <App />
  </ChannelsProvider>
</BrowserRouter>

• Next, import and use the ChannelsRibbon component exposed from @tata-digital/pwa-channels-sdk package inside the Home component to render the Channels SDK Ribbon on the Homepage.

import React from 'react'
import { ChannelsRibbon } from '@tata-digital/pwa-channels-sdk'

const Home = () => (
  <>
    <ChannelsRibbon />
  </>
)

• Next, please add the /channels route in your routing setup as shown below. This will setup the routes being served by @tata-digital/pwa-channels-sdk after integration with the main application.

import { ChannelsRoot } from '@tata-digital/pwa-channels-sdk';

<Switch>
  <Route exact path="/" component={Home} />
  <Route path="/channels" component={ChannelsRoot} />
</Switch>

Please make sure that you do not use the exact keyword for the /channels route setup, since internally ChannelsRoot uses nested routing to setup all the different routes being served by Channels SDK.

Final Layout

• Home.js

import React from 'react'
import { ChannelsRibbon } from '@tata-digital/pwa-channels-sdk'

const Home = () => (
  <>
    <ChannelsRibbon />
  </>
)

• App.js

import React, { Component } from 'react'
import { BrowserRouter, Route, Switch } from "react-router-dom"
import { ChannelsProvider, ChannelsRoot } from '@tata-digital/pwa-channels-sdk'
import '@tata-digital/pwa-channels-sdk/dist/index.css'

const config = {
  mode: 'dev',   // dev, prod
  apiBaseUrl: 'https://dapi.tatadigital.com/channelssdkdev'
}

class App extends Component {
  render () {
    return (
      <BrowserRouter>
        <ChannelsProvider config={config}>
          <Switch>
            <Route exact path="/" component={Home} />
            <Route path="/channels" component={ChannelsRoot} />
          </Switch>
        </ChannelsProvider>
      </BrowserRouter>
    )
  }
}

Register Callbacks

You can register different callbacks with the Channels SDK during the initial setup. These callbacks could later be called by the Channels SDK to notify the main application about the different pre-defined events.

Currently, we support the following callbacks:

• userAction(): This callback is triggered by the SDK when a user clicks on some CTA inside the Channels pages. This callback gets passed an object actionObj as the argument which has type and deeplink as its properties. In short, actionObj.deeplink is the url to which the user is expected to be navigated when this callback is invoked.
• channelsLoaded(): This callback is triggered by the SDK to notify the status of the loading of the channels SDK to the main application. The argument passed to the callback is true to notify the successful loading of the Channels, and false is passed in case the channels SDK fails to load.
• eventOccurred(): This callback is triggered by the SDK for special events. For example when a payment request is expired this callback is triggered. This callback is passed with a string eventType ie. name of the event and an object additionalParams containing additional information about the event.
• toggleTabbar(): This callback is triggered by the SDK to notify hide or show bottom navigation tab bar to the main application. The argument passed to the callback is true to show tab bar with 2nd ( conversation ) tab as active and false is passed to hide bottom navigation tab bar.
• unreadChannelsCount(): This callback is triggered by the SDK to notify the status of the channels having unread messages to the main application. The argument passed to the callback is a numeric value expressing the total number of channel having unread messages, 0 means no unread messages.

For registering callbacks, you can put them in the config object passed to the Channels SDK during the initial setup.

const userAction = (actionObj) => {
  window.location.assign(actionObj.deeplink)
}

const channelsLoaded = (flag) => {
  if (flag) console.log('Channels loaded successfully.');
  else console.log('Channels loading failed!');
}

const eventOccurred = (eventType,additionalParams) => {
  if(eventType === 'paymentExpiry'){
    //update the payment request widget
  }
}

const toggleTabbar = (showTabs) => {
  if (showTabs) // bottom navigation tab bar will be shown with 2nd ( conversation ) tab as active
  else // hide the bottom navigation tab bar
}
const unreadChannelsCount = (count) => {
  // count: total number of channels having unread messages
}

const config = {
  mode: 'dev',   // dev, prod
  apiBaseUrl: 'https://dapi.tatadigital.com/channelssdkdev',
  callbacks: { userAction, channelsLoaded, eventOccurred, unreadChannelsCount, toggleTabbar }
}

Exposed Methods

Channels SDK exposes different methods which can be invoked by the main application when it wants to interact with the SDK. Apart from sdk/user initialization interface, these methods serve as the primary way of handling situations when the main application wants to send some data to the Channels SDK or it wants to get information about some instantaneous (current) state inside the Channels SDK.

@tata-digital/pwa-channels-sdk exposes an HOC withChannels() which provides access to the methods exposed by the SDK.

import { withChannels } from '@tata-digital/pwa-channels-sdk'

const App = (props) => {
  console.log(props.channels)  // shows methods exposed

  return (
    ...
  )
}

export default withChannels(App)

As shown above, the channels property of the component props gives the main application access to all the methods exposed by the Channels SDK.

Currently, we expose the following methods:

• initSdk({ accountId })
  • Required - accountId: string
  • Initialize the SDK with the main application's account Id.
  • NOTE: The initSdk method is supposed to be called as soon as your web application is mounted in the browser even if the user has not logged-in yet.
• initUser({ userId, firstName?, lastName? })
  • Required - userId: string
  • Optional - firstName: string, lastName: string
  • Initialize the current user by providing user id and optionally their first and last name.
  • Please initialize the SDK first, before calling this method.
  • NOTE: The initUser method is expected to be called after the user has successfully logged-in into your web application.
• reset()
  • Resets the Channels SDK to its initial state by uninitializing/resetting the sdk and user data.
• getStatus()
  • Get the current status for the SDK along with information related to the current user, installed sdk version, etc.
• pushNotification(pushObjectData, history)
  • Required - pushObjectData: object, history: RouteComponentProps.history
  • pushObjectData.customParams is an object received during push notification.
• viewRibbon(view)
  • Required - view: boolean
  • Hide and show ribbon based on passed view.
• openChannelPage(programId)
  • Required - programId: string
  • Navigate to the channel whose programId is passed into the function