expo-pngme-sdk

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 expo-pngme-sdk

Npm

$ npm install expo-pngme-sdk --save

or

$ expo install expo-pngme-sdk

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

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

// 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:

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: '[email protected]', // 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:

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:

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:

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:

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:

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:

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