# @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 ( Your app content.. ); } ``` ### 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