npm package: @sap_oss/gigya-react-native-plugin-for-sap-customer-data-cloud
Description: A React Native plugin for interfacing SAP Customer Data Cloud
Author: SAP
Latest version: 0.6.3

# React Native plug-in for SAP Customer Data Cloud
[![REUSE status](https://api.reuse.software/badge/github.com/SAP/gigya-react-native-plugin-for-sap-customer-data-cloud)](https://api.reuse.software/info/github.com/SAP/gigya-react-native-plugin-for-sap-customer-data-cloud)

## Description
A React Native plugin for interfacing with SAP Customer Data Cloud. This plugin provides quick access to core elements & business API flows available within SAP Customer Data Cloud; designed for React Native mobile applications.


## Requirements
Android SDK support requires Android SDK 23 and above (For Biometric capabilities, SDK 23 and above is required).
iOS support requires iOS 10 and above.

## Download and Installation
Add the plugin in your **package.json** file.

## Setup & Gigya core integration

### Android setup

### Android v7 upgrade
Plugin version 0.3.0+ will depend on Android SDK core v7.
Required changes to your plugin based on Android SDK core v7 are documented in the [Android core documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#upgrading-to-v7)

Add the following to your *MainApplication.java* file:

```java
@Override
  public void onCreate() {
    super.onCreate();
    SoLoader.init(this, /* native exopackage */ false);
    initializeFlipper(this, getReactNativeHost().getReactInstanceManager());

    // Set and initialize the account schema for the Gigya core SDK.
    GigyaSdkModule.setSchema(this, GigyaAccount.class);
  }
```

### iOS setup

Navigate to **AppDelegate.m** and add the following under the:
 **(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions** method.

```objc
GigyaExtension * gigya = [[GigyaExtension alloc] init];
[gigya setMySchema];
```

To apply your custom schema, you will need to create a 'swift bridge' file and register it as follows:

```swift 
@objc public class GigyaExtension: NSObject {
    @objc func setMySchema() {
        GigyaSdk.setSchema(HostModel.self)
    }
}
```
And then call the function from your **AppDelegate.m** file.

## SDK initialization

In your application code, you can initialize the Gigya SDK using the following call:

```javascript
Gigya.initFor("Your API KEY", "API DOMAIN");
```

If you do not specify the "API DOMAIN" (as implemented in the sample application) the SDK will use the default **us1.gigya.com** domain.

## Run the example application

To run the example application included in the repository:
1. Checkout the repository code.
2. Navigate to the example folder and run the *yarn install* command.
3. Navigate to the example/ios folder and run the *pod install* command.

** Android - If changing the API key, make sure to update the signingConfigs section as the example app includes a specific keystore path 
used for testing purposes *** 

```
signingConfigs {

        debug {
            storeFile file('debug.keystore')
            storePassword 'android'
            keyAlias 'androiddebugkey'
            keyPassword 'android'
        }
    }
```

## Sending a simple request

Sending a request is available using the plugin's **send** method.
```javascript
try {
      const send = await Gigya.send("socialize.getSDKConfig");
      console.log("send: " + JSON.stringify(senddd));
    } catch (error) {
      console.log("errorSend:" + error);
    }
```

## Business APIs

The plugin provides an interface to these core SDK business APIs:
**login, register, getAccount, setAccount, isLoggedIn ,logOut, addConnection, removeConnection**
Implement them using the same request structure as shown above. 
The example application includes various different implementations.

## Social login

Use the "socialLogin" interface to perform social login using supported providers.
The React Native plugin supports the same *providers supported by the Core Gigya SDK. 

Supported social login providers:
google, facebook, line, wechat, apple, amazon, linkedin, yahoo.

For example:

```javascript
const send = await Gigya.socialLogin("facebook");
```

## Embedded social providers

# Android v7 upgrade
Plugin version 0.3.0+ will depend on Android SDK core v7.
Please view the changes required to be made to yours applicationin the [Android code documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#configuring-native-login) for updateing to external providers usage. 

Specific social providers (Facebook, Google) require additional setup. This is due to their requirement for specific (embedded native) SDKs.

To register social providers you will need to create a 'swift bridge' file (same as with using a custom schema).
Don't forget to add the relevant wrappers to the ios folder.

### Facebook

Follow the core SDK documentation and instructions for setting up Facebook login.
[Android documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#facebook)
[iOS documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#facebook)

### Google

Follow the core SDK documentation and instructions for setting up Google login.
[Android documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#google)
[iOS documentation](https://sap.github.io/gigya-swift-sdk/GigyaSwift/#google)

### LINE

To provide support for LINE as a provider, please follow it's core SDK documentation.
[Android documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#line)
[iOS documentation](https://sap.github.io/gigya-swift-sdk/GigyaSwift/#line)

### WeChat

To provider support for WeChat as a provider, please follow the core SDK documentation.
[Android documentation](https://sap.github.io/gigya-android-sdk/sdk-core/#wechat)
[iOS documentation](https://sap.github.io/gigya-swift-sdk/GigyaSwift/#wechat)

## Using screen-sets

The plugin supports the use of Web screen-sets using the following:
```javascript
Gigya.showScreenSet("Default-RegistrationLogin", (event, data) => {
      console.log(`event: ${event}`);
      if (event == "onLogin") {
        updateIsLoggedIn(Gigya.isLoggedIn())
      }
    })
```
Optional {params} map is available.

As in the core SDKs, the plugin provides a streaming channel that will stream the
Screen-Sets events (event, map).

event - actual event name.
data - event data map.

## Mobile SSO

The plugin supports the native SDK's "Single Sign On feature".
[Andorid](https://sap.github.io/gigya-android-sdk/sdk-core/#sso-single-sign-on)
[iOS](https://sap.github.io/gigya-swift-sdk/GigyaSwift/#sso-single-sign-on)

Please make sure to implement the nessesary steps described for each platform.

To initiate the flow run the following snippet.
```javascript
 const send = await Gigya.sso();
 });
```

## Session Exchange Between Mobile & WebView

Applications (mobile/web) within the same site group are now able to share a session from the mobile application to a web page running the JS SDK.

Follow these steps to allow session exchange:

1. Use the “getAuthCode” interface. This call will provide you with the required code that the web page will require for the exchange.
```javascript
var code = await Gigya.getAuthCode()
```

2. Add these URL parameters to your hosted page/website URL using the provided code:
   *** https://page-url?authCode=code&gig_actions=sso.login ***

3. Make sure that the WebView element you are using to open the URL has JavaScript enabled.

4. Once the page is loaded, the JS SDK will exchange the token provided for a valid session.


**Note:**
When using mobile SSO (single sign-on using the central login page), logging out using the SDK's logout method will only log the user out of the current API key used.
The user will not be logged out of the other group sites.

## Resolving interruptions

Much like our core SDKs, resolving interruptions is available using the plugin.

Current supporting interruptions:
* pendingRegistration
* conflictingAccounts

Example for resolving **conflictingAccounts** interruptions:
```javascript
try {
      const send = await Gigya.register(login, password, { 'sessionExpiration': 0 });
      console.log("send: " + JSON.stringify(senddd));
      updateIsLoggedIn(Gigya.isLoggedIn())

    } catch (error) {
      console.log("register error:" + error);

      const e = error as GigyaError;
      switch (e.getInterruption()) {
        case GigyaInterruption.conflictingAccounts: {
          const resolver = Gigya.resolverFactory.getResolver(e) as LinkAccountResolver;

          console.log("link:")
          console.log(resolver.regToken)

          break
        }
      }
    }
```
Once you reference your resolver, create your relevant UI to refelct if a site or social linking is
required (see example app for details) and use the relevant method.

Example of resolving link to the site when trying to link a new social account to a site account.
```javascript
const loginToSite = await resolver.linkToSite(userData.login, userData.password)
```

## Biometric support

The plugin provides Android/iOS biometric support for these flows.

```
An end user logs in.
An end user decides to use biometric authentication.
This requires the end user to verify their fingerprint.
The app is locked or deleted from memory.
The end user needs to unlock the app to restore his session.
In this case, the end user needs to verify his fingerprint.
The end user decides not to use biometric authentication
```
The biometric fingerprint feature is a security cipher that is placed on top of an existing session of your app, so invoking biometric operations requires a valid session.

Please make sure you are using native implementations:

# iOS 1. The device has a passcode.
2. the device has TouchID/FaceID.

**FaceID
To use FaceID in a compatible device, you must include the following key in your Info.plist file.

**NSFaceIDUsageDescription = (String) "Your own message "**.
If you also want to set a custom text in the Touch ID prompt, you can include the following key:

**GigyaTouchIDMessage = (String) "Your custom message" (Default = "Please authenticate to continue").**

# Android

1. Android SDK 23 and above is required.
2. the device has a fingerprint sensor.
3. at least 1 fingerprint is already registered on the device.
4. appropriate permissions are already requested in the library manifest: android.permission.USE _FINGERPRINT android.permission. USE _BIOMETRIC

**Declaring the prompt display**.
Andorid's biometric authentication uses a prompt display. You can customize the text displayed by declaring your own ***BiometricPromptInfo*** object.

In your application class (after launching the SDK), you can add the following:
```java
GigyaSdkBiometricModule.setBiometricPromptInfo(new GigyaPromptInfo( "title", "subtitle", "description" ));
```

If no prompt info is specified, the prompt window uses default English texts.

# Errors
Biometric errors from version **0.2.0** will return as String values and not as Boolean values.
This is to accomodate unique errors such as "Key invalidated", which will render the session as unrecoverable and require the user to re-authenticate.


## FIDO/WebAuthn Authentication

FIDO is a passwordless authentication method that allows password-only logins to be replaced with secure and fast login experiences across websites and apps.
Our SDK provides an interface to register a passkey or login, revoke passkeys created using FIDO/Passkeys and is backed by our WebAuthn service.

Follow the platform implementation guides:
[Swift](https://sap.github.io/gigya-swift-sdk/GigyaSwift/#fidowebauthn-authentication)
[Android](https://sap.github.io/gigya-android-sdk/sdk-core/#fidowebauthn-authentication)

* Android solution has been updated to use both FIDO & passkeys

**Additional setup for Android:**
To correctly integrate Android with the FIDO library, do the following:

1. Add the following code snippet to your MainActivity class:
```
private ActivityResultLauncher<IntentSenderRequest> resultLauncher = registerForActivityResult(
            new ActivityResultContracts.StartIntentSenderForResult(),
            new ActivityResultCallback<ActivityResult>() {
                @Override
                public void onActivityResult(ActivityResult result) {
                    Gigya.getInstance().WebAuthn().handleFidoResult(result);
                }
            }
    );
```

2. Reference the "***resultLauncher***" class within the "onCreate" method of the activity.
```
@Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        GigyaWebAuthnModule.resultLauncher = resultLauncher;
    }
```
The "***resultLauncher***" object is required for intercommunicating with the FIDO library.

**Usage example**

### LOGIN:
Login with a FIDO key on Android & a passkey on iOS:

```
try {
      var operation = await Gigya.webAuthn.login()
      console.log("webAuthnLogin success " + operation)
      // Update login state.
    } catch (e) {
        console.log("webAuthnLogin error " + e)
    }
```
Login with a passkey on both Android & iOS:
```
try {
      var operation = await Gigya.webAuthn.passkeyLogin()
      console.log("webAuthnLogin success " + operation)
      // Update login state.
    } catch (e) {
        console.log("webAuthnLogin error " + e)
    }
```

### REGISTER:
Register a new FIDO key on Android & a passkey on iOS:
```
try {
      var operation = await Gigya.webAuthn.register()
      console.log("webAuthnRegister success " + operation)
    } catch (e) {
        console.log("webAuthnRegister error " + e)
    } 
```
Register a new Passkey on both Android & iOS:
```
try {
      var operation = await Gigya.webAuthn.passkeyRegister()
      console.log("webAuthnRegister success " + operation)
    } catch (e) {
        console.log("webAuthnRegister error " + e)
    } 
```

### REVOKE:
Revoke an existing FIDO key on Android and all passkeys on iOS:
Using this method will revoke only keys that were created using the native register method. It will
not revoke keys created using the web interface (screen-sets)
```
try {
      var operation = await Gigya.webAuthn.revoke()
      console.log("webAuthnRevoke success " + operation)
      // Update login state.
    } catch (e) {
        console.log("webAuthnRevoke error " + e)
    }
 ```

Revoke a specific passkey on both Android & iOS.
Specific key is fetched using the "getCredentials" method only. This is relevant for both native/web keys.
```
try {
      var operation = await Gigya.webAuthn.passkeyRevoke("ID_TO_REVOKE")
      console.log("webAuthnRevoke success " + operation)
      // Update login state.
    } catch (e) {
        console.log("webAuthnRevoke error " + e)
    }
```
***Note:*** *The key to revoke can be obtained from the new passkeyGetCredentials method available.
```
try {
      var operation = await Gigya.webAuthn.passkeyGetCredentials()
      console.log("webAuthnGetCredentials success:\n" + JSON.stringify(operation))
    } catch (error) {
      console.log("webAuthnGetCredentials:\n" + JSON.stringify(e))
    }
```


## Known Issues
None

## How to obtain support
* [Via Github issues](https://github.com/SAP/gigya-react-native-plugin-for-sap-customer-data-cloud/issues)
* [Via SAP standard support](https://help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD/e0f596a1d9db4c318e0595bdc2e8e064/486ef9f23b554943a7d9381927c5b3f5.html)

## Contributing
Via pull request to this repository.
Please read the CONTRIBUTING file for guidelines.

## To-Do (upcoming changes)
None

## Licensing
Please see our [LICENSE](https://github.com/SAP/gigya-react-native-plugin-for-sap-customer-data-cloud/blob/main/LICENSE) for copyright and license information.