@pngme/react-native-sms-pngme-android/README.md

Module for Pngme partners to build credit score from phone information

# @pngme/react-native-sms-pngme-android

Module that supports interaction with the Messaging API on Android getting phone SMS in order to be sent to pngme platform.

The package allows you to:

- Ask for SMS permissions
- Get messages
- Send the data to pngme server
- Customize dialog styling
- Check permission status
- Retrieve user UUID

## Installation

#### Yarn

`$ yarn add @pngme/react-native-sms-pngme-android`

#### Npm

`$ npm install @pngme/react-native-sms-pngme-android --save`

### for React-Native < 0.61

`$ react-native link @pngme/react-native-sms-pngme-android`

For React-Native < 0.61 projects add maven as repository on/Android folder open build.gradle and the following line

```gradle
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' } // <-- add this line
    }
}
```

Also make sure that your gradle.properties has the following properties

```
android.useAndroidX=true
android.enableJetifier=true
```

### for React-Native > 0.61

You do not have to do anything else.

## Installation Tips

For some react-native version there is a dependency collision with `kotlinx-coroutines-core` if you get this error you can fix it by replacing this module on that way on your App gradle

```gradle
// add from here
configurations {
    implementation {
        exclude group: 'org.jetbrains.kotlinx', module: 'kotlinx-coroutines-core'
    }
}
// to here

dependencies {
    implementation ....
     // For RN 0.61.0
    implementation 'androidx.swiperefreshlayout:swiperefreshlayout:1.0.0'
}
```

We highly recommend to use JDK 11
if you have any issues please try to update your JDK version first https://www.oracle.com/java/technologies/javase-downloads.html

## Basic Usage

### Standard Integration

The simplest way to integrate the SDK is using the `go()` function:

```js
import * as React from 'react';
import { useEffect } from 'react';
import { View, Text, Alert } from 'react-native';
import { go, PNGME_RESPONSES } from '@pngme/react-native-sms-pngme-android';

export default function App() {
  useEffect(() => {
    openSDK();
  }, []);

  const openSDK = async () => {
    const goParams = {
      clientKey: 'your-client-key',
      companyName: 'Your Company Name',
      externalId: 'unique-user-id',
      firstName: 'John', // Optional
      lastName: 'Doe', // Optional
      email: 'john.doe@example.com', // Optional
      phoneNumber: '254734567890', // Optional
    };
    
    const response = await go(goParams);
    
    if (response === PNGME_RESPONSES.SUCCESS) {
      Alert.alert('Success', 'SMS data collection completed');
    } else if (response === PNGME_RESPONSES.ERROR) {
      Alert.alert('Error', 'Failed to complete SMS data collection');
    } else if (response === PNGME_RESPONSES.IOS_INCOMPATIBLE) {
      Alert.alert('Not Supported', 'This SDK only works on Android');
    }
  };

  return (
    <View>
      <Text>Your app content..</Text>
    </View>
  );
}
```

### Custom Styling

You can customize the appearance of the SDK dialogs:

```js
import { goWithStyle, setDefaultStyle, clearDefaultStyle } from '@pngme/react-native-sms-pngme-android';

const customStyle = {
  primaryColor: '#007AFF',
  backgroundColor: '#FFFFFF',
  textColor: '#000000',
  buttonBackgroundColor: '#007AFF',
  buttonTextColor: '#FFFFFF',
  titleTextSize: 18,
  bodyTextSize: 14,
  buttonTextSize: 16,
  customTitle: 'Custom Permission Title',
  customSmsDescription: 'We need access to your SMS to provide better services.',
  customPrivacyDescription: 'Your privacy is important to us.',
  customButtonText: 'Grant Permission',
  buttonCornerRadius: 8,
  buttonElevation: 4,
  privacyPolicyUrl: 'https://yourcompany.com/privacy',
  eulaUrl: 'https://yourcompany.com/terms'
};

// Option 1: Use custom style for a single call
const response = await goWithStyle(goParams, customStyle);

// Option 2: Set a default style for all SDK calls
setDefaultStyle(customStyle);
const response = await go(goParams); // Will use the default style

// Option 3: Clear default style to revert to original Pngme styling
clearDefaultStyle();
```

### Backward Compatibility

The `goWithCustomDialog` method is still available for backward compatibility but is deprecated:

```js
import { goWithCustomDialog } from '@pngme/react-native-sms-pngme-android';

// This method now maps to the standard go() method
// The hasAcceptedTerms parameter is ignored as it's handled internally
const response = await goWithCustomDialog({
  clientKey: 'your-client-key',
  companyName: 'Your Company Name',
  externalId: 'unique-user-id',
  hasAcceptedTerms: true // This parameter is ignored
});
```

## Parameters

### GoParams

| Param        | Required | Type   | Description                                                                                                                                                                                                                                                               |
| ------------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clientKey    | Yes      | String | Your client key provided by Pngme team. For security reasons avoid hardcoding this key in your code, we highly recommend using it from your .env file                                                                                                                   |
| companyName  | Yes      | String | Used to show your company name on components                                                                                                                                                                                                                              |
| externalId   | Yes      | String | You can pass your uuid in this field, this can be useful to identify your users later when obtaining processed data from our servers                                                                                                                                     |
| firstName    | No       | String | User's first name                                                                                                                                                                                                                                                         |
| lastName     | No       | String | User's last name                                                                                                                                                                                                                                                          |
| email        | No       | String | User's email address. Warning: Pngme assumes that this data is verified by your app. If email is not verified please let support team know                                                                                                                              |
| phoneNumber  | No       | String | Country code + phone number string. E.g: for Ghana (country code +233) phone number 03X XXX XXXX you should pass '+23303XXXXXXX' Warning: Pngme assumes that this data is verified by your app. If phoneNumber is not verified please let support team know |

### PngmeDialogStyle

| Param                     | Type   | Description                                           |
| ------------------------- | ------ | ----------------------------------------------------- |
| primaryColor              | String | Primary color for the dialog (hex format: #RRGGBB)   |
| backgroundColor           | String | Background color for the dialog                       |
| textColor                 | String | Text color for dialog content                         |
| buttonBackgroundColor     | String | Background color for buttons                          |
| buttonTextColor           | String | Text color for buttons                                |
| titleTextSize             | Number | Font size for dialog title                            |
| bodyTextSize              | Number | Font size for dialog body text                        |
| buttonTextSize            | Number | Font size for button text                             |
| customTitle               | String | Custom title for the dialog                           |
| customSmsDescription      | String | Custom description for SMS permission request         |
| customPrivacyDescription  | String | Custom privacy description                            |
| customButtonText          | String | Custom text for the permission button                 |
| buttonCornerRadius        | Number | Corner radius for buttons                             |
| buttonElevation           | Number | Elevation/shadow for buttons                          |
| privacyPolicyUrl          | String | URL to your privacy policy                            |
| eulaUrl                   | String | URL to your end user license agreement               |

## Utility Methods

### Check Permission Status

You can check if SMS permissions are already granted:

```js
import { isPermissionGranted } from '@pngme/react-native-sms-pngme-android';

const checkPermissions = async () => {
  const hasPermission = await isPermissionGranted();
  console.log('SMS permission granted:', hasPermission);
  
  if (!hasPermission) {
    // Show your SDK flow
    const response = await go(goParams);
  }
};
```

### Get User UUID

Retrieve the current user's UUID:

```js
import { getUserUuid } from '@pngme/react-native-sms-pngme-android';

const getUserId = async () => {
  const userUuid = await getUserUuid();
  if (userUuid) {
    console.log('User UUID:', userUuid);
  } else {
    console.log('No user UUID available');
  }
};
```

## Response Constants

The SDK provides response constants for easy handling:

```js
import { PNGME_RESPONSES } from '@pngme/react-native-sms-pngme-android';

// Available constants:
// PNGME_RESPONSES.SUCCESS - SDK completed successfully
// PNGME_RESPONSES.ERROR - SDK encountered an error
// PNGME_RESPONSES.IOS_INCOMPATIBLE - SDK called on iOS (not supported)
```

## Platform Support

This SDK only supports Android. When called on iOS, it will return `PNGME_RESPONSES.IOS_INCOMPATIBLE`.

## Error Handling

The SDK handles errors gracefully and returns appropriate response codes. Always check the response to handle different scenarios:

```js
const response = await go(goParams);

switch (response) {
  case PNGME_RESPONSES.SUCCESS:
    // Handle success
    break;
  case PNGME_RESPONSES.ERROR:
    // Handle error
    break;
  case PNGME_RESPONSES.IOS_INCOMPATIBLE:
    // Handle iOS incompatibility
    break;
  default:
    // Handle unexpected response
    break;
}
```

## Migration from Previous Versions

If you're upgrading from a previous version:

1. **goWithCustomDialog is deprecated**: Use `go()` or `goWithStyle()` instead
2. **hasAcceptedTerms parameter is no longer needed**: The SDK handles terms acceptance internally
3. **New styling options**: Use `goWithStyle()`, `setDefaultStyle()`, or `clearDefaultStyle()` for customization
4. **New utility methods**: `getUserUuid()` is now available
5. **Response constants**: Use `PNGME_RESPONSES` instead of hardcoded strings

## License

MIT