Purple Links

A lightweight React Native deep linking SDK for session-only attribution. Purple Links allows you to generate links with custom data and attribute them back to the user upon app initialization.

Features

• 🔗 Deep Linking: Seamlessly handle deep links and attribute installs/opens.
• 📊 Attribution: Pass custom data through links and retrieve it in the app.
• 📱 Device Fingerprinting: enhancing attribution accuracy.
• 🏎️ Lightweight: Minimal impact on bundle size.

Installation

npm install @purple-links/react-native
# or
yarn add @purple-links/react-native

Getting Started

1. Get your Organization ID

To use Purple Links, you need a valid Organization ID ("Org ID"). You can obtain your Org ID by signing up at purplelinks.com.

2. Initialize the SDK

Initialize the SDK as early as possible in your application's lifecycle, typically in your root component's useEffect.

import PurpleLinks from '@purple-links/react-native';

const App = () => {
  useEffect(() => {
    const initSDK = async () => {
      try {
        await PurpleLinks.init('YOUR_ORG_ID');
        console.log('PurpleLinks initialized successfully');
      } catch (error) {
        console.error('Failed to initialize PurpleLinks:', error);
      }
    };

    initSDK();
  }, []);

  return <YourAppContent />;
};

Usage

Generating Links

Create tracking links to share with users. These links can contain custom data payload that you can retrieve later.

try {
  const link = await PurpleLinks.generateLink({
    campaign: 'summer_promo',
    source: 'facebook',
    medium: 'social',
    identifier: 'ref_123456',
    discount: 20
  });
  console.log('Share this link:', link);
} catch (error) {
  console.error('Error generating link:', error);
}

Handling Deep Links

Check for deep link data when your app opens.

useEffect(() => {
  const checkDeepLink = async () => {
    const data = await PurpleLinks.deepLink();
    if (data) {
      console.log('App opened via Purple Link with data:', data);
      // specific logic based on data (e.g. navigate to screen, apply discount)
    }
  };

  checkDeepLink();
}, []);

API Reference

init(orgId: string): Promise<void>

Initializes the SDK and verifies the organization ID.

• orgId: Your unique Organization ID from purplelinks.com.
• Returns: A Promise that resolves when initialization is complete.

generateLink(data: LinkData): Promise<string>

Generates a tracking link with your custom data embedded.

• data: An object containing key-value pairs (LinkData).
  • Standard fields: campaign, source, medium, content, term, identifier, navigate, metadata.
  • Any other custom fields are allowed in metadata.
• Returns: A Promise that resolves to the tracking URL string.

deepLink(): Promise<string | null>

Checks if the current session was initiated via a tracking link and returns the associated data.

• Returns: A Promise that resolves to the data string (or object depending on backend response) if found, or null.

getDeviceDetails(): Partial<SessionState>

Retrieves the device details and session state (such as init/loading status) captured during initialization/api calls.

• Returns: An object containing device_type (ios/android) string, screen_fingerprint string, initialized boolean, and loading boolean.

License

MIT