react-native-cirrusmd-sdk

Beta Note: react-native-cirrusmd-sdk is currently in beta and does not contain all of the features available in the native CirrussMD SDKs. A full release will be available in the future.

A React Native bridge for the CirrusMDSDK. It enables customers of CirrusMD to interact with the CirrusMDSDK within a React Native app.

• Installation
• Example Project
• Basic Usage
• Advanced Usage
  • Configuration
  • Push Notifications
• Native Documentation
• License

Installation

npm install react-native-cirrusmd-sdk

iOS Note 1: You will need to add a couple of sources to your Podfile as well as use_frameworks!. A full example Podfile can be found on the CirrusMD-iOS-SDK-Example. Typically after adding a new source you will need to run pod install --repo-update for it to correctly pull from the new source.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/CirrusMD/podspecs.git'

use_frameworks!

iOS Note 2: You will need to have Module Stability enabled on your project. This is controlled by the Build Libraries for Distribution setting in Xcode. More information on this and a workaround can be found in CirrusMD-iOS-SDK-Example.

Example Project

See the example project within this repository which demonstrates a simple intregation of this React Native bridge for CirrusMDSDK. It follows the Basic Usage directions.

Basic Usage

Basic usage of of the CirrusMDSDK is very simple.

1. Import CirrusmdSdk
2. Obtain a user access token from your mobile API via the CirrusMD SDK authentication API
3. Set the CirrusMD provided secret on the SDK
4. Set the access token on the SDK
5. Show CirrusmdSdk

The details

1. import CirrusMDSDK. You will also need to import the constants from react-native-cirrusmd-sdk, used to identify the event type and stream ID parameter keys.

import CirrusmdSdk, {
  NOTIFICATION_KEY_EVENT_TYPE,
  NOTIFICATION_KEY_STREAM_ID,
  TokenStatus,
  useTokenStatus,
} from 'react-native-cirrusmd-sdk'

2. Documentation on obtaining a user access token can be found on the the CirrusMD SDK authentication API

3. Set the CirrusMD provided secret. The secret is unique to your organization. To receive a valid client secret contact your account representative at CirrusMD. The secret must be set prior to setting the token in the next step. You must also set the secret after logging out of the SDK.

CirrusmdSdk.setSecret('CIRRUSMD-PROVIDED-SECRET')

4. AFTER setting the secret on the SDK, set the token. The TokenStatus that is emitted will provide information on whether the token provided to the SDK was able to load a patient, and if not provides an error with some details on what went wrong.

CirrusmdSdk.setToken(data.token)

const checkStatus = (tokenStatus) => {
  switch (tokenStatus) {
    case TokenStatus.INVALID_TOKEN:
      console.log('Error: Invalid Token')
    case TokenStatus.NO_SECRET_PROVIDED:
      console.log('Error: No Sectret Provided')
    case TokenStatus.SERVICE_UNAVAILABLE:
      console.log('Error: Service Unavailable')
    case TokenStatus.SUCCESS:
      console.log('CirrusmdSdk Success, ready to show CirrumdSdk')
    default:
      console.log('Awaiting token status from CirrusmdSdk')
  }
}

5. When ready (for example on TokenStatus.SUCCESS or user taps button) show CirrusmdSdk. On iOS CirrusmdSdk is presented in a modal over your app. On Android CirrusmdSdk is presented in a new Activity that is shown full screen.

CirrusmdSdk.showCirrusmdSdk()

Advanced Usage

Configuration

CirrusmdSdk allows for some simple configuration. A custom title can be set and the settings view, user log out, and dependents features can enabled or disabled. All optional features are disabled by default.

Note: The title configuration only applies to iOS as it uses a standard UINavigationController that has room for a title where Android does not.

CirrusmdSdk.configure(
  'Example Title', // title
  true, // enableSettings
  true, // enableUserLogOut
  true // enableDependents
)

Push Notifications

Push notifications for the CirrusmdSdk are configured slightly differently than the native configuration. Documentation on setting up configurations natively can be found in CirrusMD-iOS-SDK-Example Push Notifications and CirrusMD-Android-SDK-Example Push Notifications

To configure push notifications, first follow the Getting Started set up instructions from the React Native Firebase library.

Next follow the React Native Push Notifications instructions to install and configure the library, this helps deal with permissions and notification manipulation.

As part of the configuration set up above, verify that the following is pasted inside of the native apps.

Paste this at the bottom of the AndroidManifest.xml file at the bottom inside the application

      <service
          android:name="com.dieam.reactnativepushnotification.modules.RNPushNotificationListenerService"
          android:exported="false" >
          <intent-filter>
              <action android:name="com.google.firebase.MESSAGING_EVENT" />
          </intent-filter>
      </service>
    </application>

Paste this at the bottom of the AppDelegate.m file at the bottom inside the application just before the @end

    // Required for the register event.
    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
    {
      [RNCPushNotificationIOS didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
    }
    // Required for the notification event. You must call the completion handler after handling the remote notification.
    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
    {
      [RNCPushNotificationIOS didReceiveRemoteNotification:userInfo fetchCompletionHandler:completionHandler];
    }
    // Required for the registrationError event.
    - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
    {
    [RNCPushNotificationIOS didFailToRegisterForRemoteNotificationsWithError:error];
    }
    // Required for localNotification event
    - (void)userNotificationCenter:(UNUserNotificationCenter *)center
    didReceiveNotificationResponse:(UNNotificationResponse *)response
            withCompletionHandler:(void (^)(void))completionHandler
    {
      [RNCPushNotificationIOS didReceiveNotificationResponse:response];
    }

    //Called when a notification is delivered to a foreground app.
    -(void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler
    {
      completionHandler(UNNotificationPresentationOptionSound | UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionBadge);
    }

  @end

npm install --save react-native-push-notification
yarn add react-native-push-notification

Next import the folowing files classes to utilize the proper SDKs

Import PushNotification (for Android) and PushNotificationIOS (for iOS) libraries

import PushNotification from 'react-native-push-notification'
import PushNotificationIOS from '@react-native-community/push-notification-ios'

Configure PushNotification:

PushNotification.configure({
  // (optional) Called when Token is generated (iOS and Android)
  onRegister: (tokenData) => {
    const { token } = tokenData
    console.log('onRegister', token)
    CirrusmdSdk.setPushToken(token)
  },

  // (required) Called when a remote or local notification is opened or received
  onNotification: (notification) => {
    console.log('onNotification', notification)
    if (notification.userInteraction) {
      const data =
        Platform.OS === 'android' ? notification.data : notification.data.data
      const streamId: string = data?.[NOTIFICATION_KEY_STREAM_ID]
      const eventType: string = data?.[NOTIFICATION_KEY_EVENT_TYPE]
      CirrusmdSdk.showCirrusmdSdk()
      CirrusmdSdk.onPushNotificationSelected(streamId, eventType)
    }
    PushNotification.localNotification({
      channelId: channelId,
      userInfo: notification.data,
      title: notificationTitle, // Title of notification
      message: notification.data ? notification.data.message : '',
      priority: 'high',
    })
    notification.finish(PushNotificationIOS.FetchResult.NoData)
  },

  // (optional) Called when Action is pressed (Android)
  onAction: (notification) => {
    console.log('NotificationHandler.onAction:', notification)
    if (notification.action === 'Yes') {
      // PushNotification.invokeApp(notification)
    }
  },

  // (optional) Called when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a simulator. (iOS)
  onRegistrationError: (err) => {
    console.log('NotificationHandler.onRegistrationError:', err)
  },

  // IOS ONLY (optional): default: all - Permissions to register.
  permissions: {
    alert: true,
    badge: true,
    sound: true,
  },

  // Should the initial notification be popped automatically
  // default: true
  popInitialNotification: true,

  // set to false to call PushNotification.requestPermissions() after sdk is
  // initialized
  requestPermissions: false,
})

Next, handle displaying the notification functionality, updating the channelId, channelName, and localNotification title. It is necessary to create a channel for Android apps, the package name can be used if only one channel is being added for chat streams. The name is what will be visible to the user in the settings.

const channelId = 'com.testchannel.package' // YOUR CHANNEL ID
const channelName = 'Example Push Notification' // YOUR CHANNEL NAME
const notificationTitle = 'Internal Message Example'
// create push channel somewhere on initialization
PushNotification.createChannel(
  {
    channelId: channelId,
    channelName: channelName, // YOUR CHANNEL NAME
    importance: 4,
  },
  (created) => console.log(`CreateChannel returned '${created}'`)
)

Finally, ask for notification permissions when ready, the example app runs the configuration after success of setting the SDK token

const { buttonText, disabled } = React.useMemo(() => {
    console.log('received event: ', tokenStatus)
    switch (tokenStatus) {
      case TokenStatus.INVALID_TOKEN:
        return { buttonText: 'Error: Invalid Token', disabled: true }
      case TokenStatus.NO_SECRET_PROVIDED:
        return { buttonText: 'Error: No Sectret Provided', disabled: true }
      case TokenStatus.SERVICE_UNAVAILABLE:
        return { buttonText: 'Error: Service Unavailable', disabled: true }
      case TokenStatus.SUCCESS:
        PushNotification.requestPermissions()
        return { buttonText: 'Show CirrusMDSDK!', disabled: false }
      default:
        return { buttonText: 'Initializing CirrusMDSDK...', disabled: true }
    }
  }, [tokenStatus])
}

Native Documentation

Documentation of the native CirrusMDSDKs:

CirrusMD-iOS-SDK-Example

CirrusMD-Android-SDK-Example

License

react-native-cirrusmd-sdk is available under the MIT license. See the LICENSE file for more info.