@pngme/capacitor-sms-pngme

A Capacitor plugin that wraps the Pngme Android SDK to enable SMS data collection.

This module allows your application to:

• Request SMS permissions from the user.
• Collect and send SMS data to the Pngme platform.
• Customize the styling of the permission and data collection dialogs.
• Check the current SMS permission status.
• Retrieve the Pngme user UUID.

Installation

Install the package in your Capacitor project:

npm install @pngme/capacitor-sms-pngme
npx cap sync

Android Configuration

This plugin requires the jitpack.io Maven repository. Ensure it is added to your project's root build.gradle file:

// android/build.gradle
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' } // <-- Add this line
    }
}

Also, ensure your gradle.properties file has AndroidX and Jetifier enabled:

# android/gradle.properties
android.useAndroidX=true
android.enableJetifier=true

We highly recommend using JDK 11. If you encounter any build issues, please try updating your JDK version first.

Basic Usage

The simplest way to integrate the SDK is by using the go function.

import { go, PNGME_RESPONSES } from '@pngme/capacitor-sms-pngme';

const startPngmeSDK = async () => {
  try {
    const result = await go({
      clientKey: 'your-client-key',       // Provided by the Pngme team
      companyName: 'Your Company Name',  // Displayed in the SDK dialogs
      externalId: 'unique-user-id',      // A unique identifier for your user
      firstName: 'John',                 // Optional
      lastName: 'Doe',                   // Optional
      email: '[email protected]',     // Optional
      phoneNumber: '254734567890',       // Optional (E.g., +23303XXXXXXX for Ghana)
    });
    
    if (result === PNGME_RESPONSES.SUCCESS) {
      console.log('SMS data collection completed successfully.');
      alert('Success!');
    }
  } catch (error) {
    console.error('Pngme SDK Error:', error.message);
    // Handle platform errors or invalid parameters
    if (error.message.includes('Platform Error')) {
        alert('This feature is only available on Android.');
    } else {
        alert(`Error: ${error.message}`);
    }
  }
};

Custom Styling

You can customize the appearance of the SDK dialogs to match your app's branding.

import { goWithStyle, setDefaultStyle, clearDefaultStyle } from '@pngme/capacitor-sms-pngme';

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'
};

const goParams = {
  clientKey: 'your-client-key',
  companyName: 'Your Company Name',
  externalId: 'unique-user-id',
};

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

// Option 2: Set a default style for all subsequent SDK calls
setDefaultStyle(customStyle);
const responseDefault = await go(goParams); // This call will use the default style

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

API Reference

Parameters

GoParams

| Param | Required | Type | Description | | :--- | :--- | :--- | :--- | | clientKey | Yes | string | Your client key from the Pngme team. For security, load this from environment variables rather than hardcoding it. | | companyName | Yes | string | Your company name, which will be displayed to the user in the SDK components. | | externalId | Yes | string | A unique identifier for the user (e.g., a UUID from your database). | | firstName | No | string | User's first name. | | lastName | No | string | User's last name. | | email | No | string | User's email address. Pngme assumes this has been verified by your app. | | phoneNumber | No | string | User's phone number, including the country code (e.g., +23303XXXXXXX). Pngme assumes this has been verified. |

PngmeDialogStyle

| Param | Type | Description | | :--- | :--- | :--- | | primaryColor | string | Primary color for dialog accents (hex format: #RRGGBB). | | backgroundColor | string | Background color for the dialog. | | textColor | string | Text color for the dialog content. | | buttonBackgroundColor | string | Background color for buttons. | | buttonTextColor | string | Text color for buttons. | | titleTextSize | number | Font size for the dialog title. | | bodyTextSize | number | Font size for the dialog body text. | | buttonTextSize | number | Font size for button text. | | customTitle | string | A custom title for the permission dialog. | | customSmsDescription | string | Custom text explaining the need for SMS permission. | | customPrivacyDescription| string | Custom text for the privacy description. | | customButtonText | string | Custom text for the permission button. | | buttonCornerRadius | number | The corner radius for buttons. | | buttonElevation | number | The elevation (shadow) for buttons. | | privacyPolicyUrl | string | A URL to your company's privacy policy. | | eulaUrl | string | A URL to your company's End User License Agreement. |

Utility Methods

Check Permission Status

Check if SMS permission has already been granted.

import { isPermissionGranted } from '@pngme/capacitor-sms-pngme';

const checkSmsPermission = async () => {
  const hasPermission = await isPermissionGranted();
  console.log('SMS permission granted:', hasPermission);
  
  if (!hasPermission) {
    // Initiate the SDK flow if permission is not granted
    await go(goParams);
  }
};

Get User UUID

Retrieve the Pngme UUID for the current user. This is useful for associating the user in your system with their Pngme data record.

import { getUserUuid } from '@pngme/capacitor-sms-pngme';

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

Response Constants

The SDK provides constants for handling the result of the go function.

import { PNGME_RESPONSES } from '@pngme/capacitor-sms-pngme';

// Available constants:
// PNGME_RESPONSES.SUCCESS: The SDK flow completed successfully.
// PNGME_RESPONSES.ERROR: An error occurred within the native Android SDK.
// PNGME_RESPONSES.IOS_INCOMPATIBLE: The function was called on iOS, which is not supported.
// PNGME_RESPONSES.INVALID_PARAMS: Required parameters were missing or invalid.
// PNGME_RESPONSES.ACTIVITY_DOES_NOT_EXIST: The Android activity was not found.

How to Run the Example

This plugin does not ship with a standalone example app, but you can easily test it by integrating it into a new or existing Capacitor project.

1. Create a new Ionic Capacitor project (if you don't have one):

   ionic start pngme-test-app blank --type=react --capacitor
   cd pngme-test-app

2. Install the Pngme plugin:

   npm install @pngme/capacitor-sms-pngme
   npx cap sync

3. Add the Android platform:

   npx cap add android

4. Configure Android:

   • Add maven { url 'https://jitpack.io' } to your android/build.gradle file.
   • Ensure android.useAndroidX=true and android.enableJetifier=true are in android/gradle.properties.

5. Use the plugin in your app:

   • Open a page in your app (e.g., src/pages/Home.tsx).
   • Add a button and call the go function, adapting the Basic Usage example above.

6. Run the app on an Android device or emulator:

   npx cap run android

   Now you can test the full functionality of the plugin.

Platform Support

This plugin is only available for Android. Calling its functions on iOS will result in a Platform Error or return the PNGME_RESPONSES.IOS_INCOMPATIBLE constant.

License

MIT