react-native-malwarelytics/docs/Usage.md

Malwarelytics for React Native protects your banking or fintech app from a broad range of mobile security threats with an industry-leading mobile threat intelligence solution.

# Usage

Before you start using the `Malwarelytics` class you should always check the module's state: 

```typescript
const state = await Malwarelytics.sharedInstance.getState();
console.log(`Malwarelytics state is ${state}`);
```

The class can be in the following states:

- `SHUTDOWN` - Malwarelytics class is not initialized, you can call `initialize()`
- `PENDING_INIT` - Malwarelytics class is being initialized right now and you have to wait for the `READY` state.
- `READY` - Malwarelytics class is ready for use.
- `PENDING_SHUTDOWN` - Malwarelytics class is shutting down.

## Initialization result

Once the initialization is complete, then you can check the result of the initialization:

```typescript
const service = Malwarelytics.sharedInstance;
const state = await service.getState();
if (state == 'SHUTDOWN') {
    const result = await service.initialize({});   // Provide your configuration here...
    console.log(`Initialized with result = ${result}`)
} else if (state == 'READY') {
    console.log(`Already initialized with result = ${service.initializationResult}`)
}
```

 You can obtain the following values in the initialization result:
 
 - `'SUCCESS'` - Initialization completed successfully.
 - `'PERMANENT_OFFLINE_MODE'` - SDK works in a permanent offline mode, for example, if the configuration doesn't contain a `service` section.
 - `'TEMPORARY_OFFLINE_MODE'` - Android only: SDK works in a temporary offline mode.


## Shutdown

If you no longer need to use `Malwarelytics` then you can shut the module down and release allocated resources:

```typescript
await Malwarelytics.sharedInstance.shutdown();
```

## AV user ID

AV user ID (`avUid`) is randomly generated by the Malwarelytics Server. The ID is persisted between app restarts. You can use such an identifier in your systems
to identify the user's device in the Malwarelytics console.

To obtain the `avUid` call:

```typescript
const avUid = await Malwarelytics.sharedInstance.getAvUserId();
```

To reset `avUid` you need to shut down the module:

```typescript
// Boolean parameter indicating that avUid should be reset during the shutdown.
await Malwarelytics.sharedInstance.shutdown(true);
```

Resetting might be useful when e.g. a user clears his/her pairing on the device.


## Listening to state changes

To listen to the state changes you have to register the listener that implements the `MalwarelyticsStateListener` interface. For example:

```typescript
await Malwarelytics.sharedInstance.setStateListener({
    malwarelyticsStateChanged: function (state: MalwarelyticsState): void {
        console.log(`Malwarelytics state = ${state}`)
    }
})
```

To unregister a previously set listener simply call:

```typescript
Malwarelytics.sharedInstance.removeStateListener()
```

## Error Handling

All errors reported from the library are wrapped into the `MalwarelyticsError` class. The error object provides the following properties:

- `code` - error code specifying the reason for the error.
- `message` - human-readable error message.
- `originalException` - original exception, if available.

The following example shows the meaning of all supported error codes:

```typescript
try {
    await Malwarelytics.sharedInstance.getState();
} catch (error) {
    if (error instanceof MalwarelyticsError) {
        switch (error.code) {
        case 'METHOD_NOT_SUPPORTED':  // Not supported on this platform
            console.log(`Method is not supported on this platform. Details: ${JSON.stringify(error)}`);
            break;
        case 'METHOD_NOT_AVAILABLE':  // Not available in the current configuration.
            console.log(`Method is not available, change your configuration. Details: ${JSON.stringify(error)}`);
            break;
        case 'WRONG_STATE':           // Method called in wrong module's state
            console.log(`Wrong state. Details: ${JSON.stringify(error)}`);
            break;
        case 'INVALID_CONFIG':        // Property in configuration is invalid
            console.log(`Invalid object in config. Details: ${JSON.stringify(error)}`);
            break;
        case 'MISSING_CONFIG':        // Required property in configuration is missing
            console.log(`Required object in config is missing. Details: ${JSON.stringify(error)}`);
            break;
        case 'INVALID_PARAM':         // Parameter has wrong type
            console.log(`Invalid parameter. Details: ${JSON.stringify(error)}`);
            break;
        case 'MISSING_PARAM':         // Required parameter is missing
            console.log(`Required parameter is missing. Details: ${JSON.stringify(error)}`);
            break;
        case 'GENERIC_ERROR':         // Unexpected or Internal error
            console.log(`Generic error. Details: ${JSON.stringify(error)}`);
            break;
        case 'LINKING_ERROR':         // Library is not properly linked
            console.log(`Linking error. Details: ${JSON.stringify(error)}`);
            break;
        }
    }
}
```

## Read Next

- [Release Notes](Release-Notes.md)