Go Mailer Push SDK for React Native

Receive push notifications sent by Go-Mailer in your React Native app. This SDK handles device registration, user identification, and notification interaction tracking - Go-Mailer takes care of sending the notifications.

What This SDK Does

• 📱 Registers your app to receive push notifications from Go-Mailer
• 👤 Identifies users so Go-Mailer knows who to send notifications to
• 📊 Tracks interactions when users tap notifications
• 🔧 Simple Integration - just call our helper functions at the right time
• 📱 Cross-Platform - works on both iOS and Android

Installation

npm install go-mailer-push-sdk
# or
yarn add go-mailer-push-sdk

iOS Setup

1. Add to your Podfile:

pod 'GoMailer', :path => '../node_modules/go-mailer-push-sdk/ios'

2. Run:

cd ios && pod install

3. Enable Push Notifications capability in Xcode
4. Configure APNs certificates in your Apple Developer account

Android Setup

1. Add Firebase to your Android project
2. Place google-services.json in android/app/
3. The SDK handles FCM registration automatically

Quick Start

Step 1: Initialize (call once when your app starts)

import GoMailer from 'go-mailer-push-sdk';

// Initialize Go-Mailer SDK (defaults to production)
await GoMailer.initialize({
  apiKey: 'your-go-mailer-api-key'
});

Environment Configuration

The SDK supports multiple environments for testing:

// Production (default)
await GoMailer.initialize({
  apiKey: 'your-api-key',
  environment: 'production' // https://api.go-mailer.com/v1
});

// Staging
await GoMailer.initialize({
  apiKey: 'your-api-key',
  environment: 'staging' // https://api.gm-g7.xyz/v1
});

// Development
await GoMailer.initialize({
  apiKey: 'your-api-key',
  environment: 'development' // https://api.gm-g6.xyz/v1
});

// Custom endpoint
await GoMailer.initialize({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-custom-endpoint.com/v1'
});

Step 2: Identify the user (call when user logs in or you know their email)

await GoMailer.setUser({
  email: '[email protected]'
  // Add any other user properties you want Go-Mailer to know about
});

Step 3: Request permission (call when appropriate in your UX flow)

const granted = await GoMailer.requestNotificationPermission();
if (granted) {
  // User will now receive notifications sent by Go-Mailer
}

Step 4: Track clicks (call when a notification opens your app)

// Go-Mailer includes notification_id in every notification payload
await GoMailer.trackNotificationClick('notification-id-from-payload');

That's it! Go-Mailer will handle sending notifications to your users.

Complete API Reference

1. Initialize the SDK

await GoMailer.initialize({
  apiKey: 'your-go-mailer-api-key'
})

Call this once when your app starts. Required before using any other methods.

2. Identify Users

await GoMailer.setUser({
  email: '[email protected]',
  firstName: 'John',
  lastName: 'Doe'
  // ... any other user properties
})

Tell Go-Mailer who this user is so we can send them targeted notifications.

3. Handle Permissions

// Request permission to show notifications
const granted = await GoMailer.requestNotificationPermission()

// Check current permission status
const status = await GoMailer.checkNotificationPermission()

iOS requires explicit permission. Android grants it automatically in most cases.

4. Track Notification Interactions

// When user taps a notification and opens your app
await GoMailer.trackNotificationClick('notification-id-from-payload')

Important: Go-Mailer includes a notification_id in every notification we send. Extract this from the payload and pass it to this method.

5. Optional: Custom Event Tracking

// Track custom user actions (optional)
await GoMailer.trackEvent('button_clicked', { 
  button_name: 'subscribe' 
})

How Go-Mailer Sends Notifications

You don't need to worry about sending notifications - Go-Mailer handles this for you! When we send notifications to your users, we include a notification_id that you'll need to extract and use for tracking clicks.

What the notification payload looks like (for reference):

iOS:

{
  "aps": {
    "alert": {
      "title": "Hello from Go-Mailer!",
      "body": "Your notification message"
    }
  },
  "notification_id": "abc123",
  "your_custom_data": "any_value"
}

Android:

{
  "notification": {
    "title": "Hello from Go-Mailer!",
    "body": "Your notification message"
  },
  "data": {
    "notification_id": "abc123",
    "your_custom_data": "any_value"
  }
}

Your job: Extract the notification_id and call GoMailer.trackNotificationClick(notification_id) when the user taps the notification.

Troubleshooting

Common Issues

"SDK not initialized"

• Make sure you call GoMailer.initialize() before any other methods

"Permission denied" on iOS

• iOS requires explicit permission. Call requestNotificationPermission()
• Check your app's notification settings in iOS Settings

"Notifications not received"

• Verify your Firebase setup (Android) or APNs certificates (iOS)
• Check that setUser() was called with a valid email
• Ensure Go-Mailer has your correct push certificates/keys

"Click tracking not working"

• Make sure you're extracting notification_id from the payload correctly
• Call trackNotificationClick() when the notification opens your app, not when it's received

Example Implementation

import GoMailer from 'go-mailer-push-sdk';
import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    // Initialize on app start
    GoMailer.initialize({ apiKey: 'your-api-key' });
  }, []);

  const handleLogin = async (email: string) => {
    // Identify user after login
    await GoMailer.setUser({ email });
    
    // Request permission at the right moment
    const granted = await GoMailer.requestNotificationPermission();
    if (granted) {
      console.log('User will receive Go-Mailer notifications');
    }
  };

  // Handle notification clicks (implementation depends on your navigation)
  const handleNotificationClick = (notificationData: any) => {
    const notificationId = notificationData.notification_id;
    if (notificationId) {
      GoMailer.trackNotificationClick(notificationId);
    }
  };

  return (
    // Your app content
  );
}

Requirements

• React Native >= 0.60.0
• iOS 10.0+ / Android API level 16+
• Valid Go-Mailer account and API key

Need Help?

• 📖 Complete Documentation
• 💬 Support
• 🐛 Report Issues

Go-Mailer - Customer engagement messaging platform
go-mailer.com