npm package: @mobify/react-native-webview-event-messaging
Description: React Native Library which adds an Event Messaging Bus to a WebView
Latest version: 0.6.0

# WebView Event Messaging Library for React Native

This library enables a react native app to communicate with a web site which is loaded inside of a web view running inside the app.

The communication between the React Native app and the site occurs over a React Native Bridge which is a bridge which enables communication between JavaScript code and Native language code.

The library is publish on [npm](https://www.npmjs.com/package/@mobify/react-native-webview-event-messaging).

The library has a associated library published on [npm](https://www.npmjs.com/package/@mobify/react-native-webview-event-messaging-web). The associated library enables the web site running inside the app to communicate back to the react native app.

Communication between the sites displayed inside the `EventMessagingWebViews` and the React Native app can be done by accessing the sites through the `EventMessenger`. The communication with the `EventMessenger` can be done directly with the `eventMessenger` instance where it was created (global scope of the app in most cases) or can be accessed through by the React Native components. In order to acceess the object in a React Native component `connectWithEventMessenger` can be used to wrap any component in order to place the instance of `eventMessenger` into the props of the wrapped component.

## Install

Run these commands:

```
npm install --save @mobify/react-native-webview-event-messaging
react-native link react-native-webview
```

Note: `react-native-version-number` is a peer dependency of the library. Ensure that it has been added and linked in the project.

## Example Usage

`main.js`

```
import React from 'react'
import ReactDOM from 'react-dom'

import { EventWebViewsProvider, EventMessagingWebView, EventMessenger } from 'react-native-webview-event-messaging'
import { NativeViews } from './NativeViews'

const eventMessenger = new EventMessenger()

const rootElement = document.getElementById('root')
ReactDOM.render(
  <EventWebViewsProvider eventMessenger= {eventMessenger} >
    <NativeViews />
    <EventMessagingWebView
      webViewIdentifier= 'CART'
     />
  </EventWebViewsProvider>,
  rootElement
)
```

`NativeViews.js`

```
import { connectWithEventMessenger } from 'react-native-webview-event-messaging'

class NativeViews extends React.Component {
  constructor(props) {
    super(props)
  }

  updateConfirmationId(data) {
    ...
  }

  componentDidMount() {
    this.eventMessenger.registerHandler('CART', 'updateConfirmationId',         this.updateConfirmationId.bind(this))
  }

  componentWillReceiveProps(nextProps) {
    const { shopperId } = this.props
    this.eventMessenger.trigger('CART', 'updateShopperId', {shopperId: shopperId})
  }

  render() {
    return <SomeLovelyNativeViews />
  }
}

export default connectWithEventMessenger(NativeViews)
```

## API

### `EventMessenger`

The EventMessenger class allows event messaging to/from a set of ReactNative WebViews

#### Methods

##### `registerHandler(webViewIdentifier, eventName, handlerFunc)`

`registerHandler` registers a handler function (`handlerFunc`) to be called when the site loaded in the web view with the identifier `webViewIdentifier` sends an event with the name `eventName`.

`handlerFunc` takes one parameter `data` which is the data payload sent with the event.

##### `trigger(webViewIdentifier, eventName, data)`

`trigger` sends an event with the event name `eventName` and an associated data payload (`data`) to the site loaded in the web view with the identifier `webViewIdentifier`.

### `EventWebViewsProvider`

Component to wrap around top level App Component. `EventWebViewsProvider` enables the `WebView` components of the app to be registered with a `EventMessenger`.

#### Props

##### `props.eventMessenger`

`props.eventMessenger` takes an instance of `EventMessenger` in order to enable access to this object by the React Native components.

### `EventMessagingWebView`

HOC which wraps the [React Native WebView Component](https://github.com/react-native-community/react-native-webview) and gives the `EventWebViewsProvider` a reference to the React Native WebView Component.

#### Props

##### `props.webViewIdentifier`

Unique identifer for the webView instance.

#### `props.previewBundleLocation`

String which specifies the location of the [Mobify Preview URL](https://docs.mobify.com/progressive-web/latest/getting-started/mobify-preview/). For example, `'https://localhost:8443/loader.js'` should be supplied when loading the Preview bundle from a local development web server.

### `connectWithEventMessenger(WrappedComponent)`

`connectWithEventMessenger` is a higher order component that allows the wrapped component (`WrappedComponent`) to communicate via eventing with a site loaded inside an `EventMessagingWebView`.

#### Props

###### `props.eventMessenger`

`EventMessenger` instance which allows event based communication with the sites loaded inside the app's webViews.

## UserAgent

The UserAgent string is altered in the react-native-webview to use `ReactNativeEventMessagingWebView/{APP_VERSION_NAME}`. This allows the library to communicate to the web page that it is running inside the `EventMessagingWebView` and allows the web page to adapt its behavior for different app versions.