npm package: @pngme/capacitor-sms-pngme
Description: Capacitor plugin wrapper around Pngme Android SDK to collect SMS data
Latest version: 0.1.1

# @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:

```bash
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:

```gradle
// 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.

```typescript
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: 'john.doe@example.com',     // 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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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):

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

2.  **Install the Pngme plugin**:

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

3.  **Add the Android platform**:

    ```bash
    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**:

    ```bash
    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