rn-prodeeplinks

React Native SDK for ProDeepLinks — deferred deep linking, attribution param handling, and MMP event tracking.

API key required: Use your publishable key (pdl_live_pk_* / pdl_test_pk_*) from prodeeplinks.com.

Version: 0.2.0

Features

• Deep link resolution (OS URL first, then fingerprint match)
• Attribution param extraction (clickId, pdlSessionId, UTMs) on launch and warm-start links
• MMP event tracking (/v1/mmp/events, batch, conversions, attribution)
• Deferred fingerprint matching (public endpoint, no auth header)
• TypeScript support

Installation

npm install rn-prodeeplinks
npm install react-native-device-info @react-native-community/netinfo

Quick start

import {
  init,
  getDeepLink,
  updateSessionId,
  setCustomerUserId,
  trackPurchase,
  isReady,
} from 'rn-prodeeplinks';

// 1. Initialize (parses cold-start deep link + runs deferred fingerprint match)
const initResult = await init({
  apiKey: 'pdl_live_pk_xxxx', // or pdl_test_pk_* for QA
});

if (!initResult.success) {
  console.error(initResult.error);
  return;
}

// 2. If your backend/native layer sends app_open and returns a sessionId:
updateSessionId(sessionIdFromBackend);

// 3. Resolve deep link URL
const link = await getDeepLink();
if (link.success && link.url) {
  console.log('Deep link:', link.url);
  // Navigate in your app using link.url / deepLinkContext
}

// 4. After login — auto-sends a login event
await setCustomerUserId('user_42');

// 5. Purchase — sends purchase event + conversion in parallel
await trackPurchase({
  revenue: 29.99,
  currency: 'USD',
  orderId: 'order_123',
  productId: 'prod_annual',
});

Deep link resolution flow

On init():

1. Parses Linking.getInitialURL() and stores clickId, pdlSessionId, and UTM params in memory
2. Registers a warm-start Linking listener for re-engagement URLs
3. Runs deferred fingerprint match in parallel when no URL is present

On getDeepLink():

1. Returns cached URL if already resolved
2. Falls back to Linking.getInitialURL()
3. Falls back to POST /custom-deep-link/fingerprint/match (public, no auth)

User taps link → OS opens app with URL
       ↓
init() stores clickId / pdlSessionId / UTMs
       ↓
getDeepLink() returns URL for navigation
       ↓
trackAnalyticsEvent / trackPurchase attach stored attribution params

App launch (app_open) — backend responsibility

This SDK does not send app_open on launch or foreground. That is handled by your backend / native MMP layer.

When your backend returns a sessionId from its app_open handling, pass it into the SDK:

updateSessionId(sessionId);

The SDK uses that sessionId on subsequent events (login, purchase, custom events, conversions).

API reference

init(config)

| Field | Type | Description | |-------|------|-------------| | apiKey | string | Preferred. Publishable key pdl_live_pk_* or pdl_test_pk_* | | licenseKey | string | Deprecated alias for apiKey | | apiBaseUrl | string | Optional. Defaults to https://api.prodeeplinks.com |

getDeepLink(callback?)

Returns { success, url, message?, error? }. URL is null when no deferred link is available.

updateSessionId(sessionId)

Sets the in-memory MMP session ID from your backend app_open layer.

setCustomerUserId(userId)

Stores the user ID and automatically sends a login event to /v1/mmp/events.

trackAnalyticsEvent(event)

Sends custom/screen events. Secondary events are batched to /v1/mmp/events/batch (max 50). login and purchase are sent immediately.

Legacy event types are mapped automatically:

| Old | Sent as | |-----|---------| | deeplink | app_open | | identify | login | | pro_track | custom |

Auth uses the x-api-key header — do not put the key in the event body.

trackPurchase(payload)

Sends both in parallel (per MMP integration guide):

• POST /v1/mmp/events with eventType: "purchase"
• POST /v1/mmp/conversions with conversionType: "purchase"

Duplicate orderId values are skipped client-side.

trackConversion(payload)

Sends a conversion to /v1/mmp/conversions. Retries attribution fetch if inline attribution is null.

getAttribution(conversionId)

Fetches attribution from GET /v1/mmp/attribution/:conversionId.

flush()

Force-flushes the in-memory event batch queue.

isReady() / reset()

Check initialization state or clear SDK runtime state.

ProDeepLink class (optional)

const pdl = new ProDeepLink({ apiKey: 'pdl_live_pk_xxxx' });
await pdl.initialize();
const result = await pdl.getDeepLinkUrl();

Authentication

| Endpoint | Auth | |----------|------| | /v1/mmp/* | x-api-key: pdl_live_pk_* (or test key) | | /custom-deep-link/fingerprint/match | None (public) | | /custom-deep-link/license/validate | None (public, body only) |

Use publishable keys (pk) in the mobile app. Never embed secret keys (sk).

Legacy keys (cdl_pub_*, CDL-V1-*) still work; the SDK logs a deprecation warning when the server returns X-Api-Key-Deprecation.

MMP endpoints used

| Method | Path | Purpose | |--------|------|---------| | POST | /v1/mmp/events | Immediate events (login, purchase, app_open) | | POST | /v1/mmp/events/batch | Batched secondary events | | POST | /v1/mmp/conversions | Conversions + attribution | | GET | /v1/mmp/attribution/:id | Attribution lookup | | POST | /custom-deep-link/fingerprint/match | Deferred deep link resolution |

TypeScript types

import type {
  InitConfig,
  InitResponse,
  DeepLinkResponse,
  CustomDeepLinkAnalyticsEvent,
  MmpConversionPayload,
  MmpConversionResponse,
  TrackPurchasePayload,
} from 'rn-prodeeplinks';

Error handling

• Invalid API key format is rejected locally before any network call
• MMP API errors return { success: false, error: string }
• Rate limit (429) responses retry with exponential backoff (up to 3 attempts)

Troubleshooting

getDeepLink() returns null

• Normal on organic installs with no prior link click
• Deferred match requires a prior tracked click within the attribution window

Events missing attribution

• Ensure init() ran before the user navigates (params are parsed on launch)
• Ensure updateSessionId() is called after your backend app_open
• Warm-start links are captured automatically via the Linking listener

401 on MMP calls

• Verify pdl_live_pk_* / pdl_test_pk_* key (not sk)
• Confirm init({ apiKey }) succeeded

Support

• Portal: prodeeplinks.com/signup
• Technical issues: contact ProDeepLinks support

License

Proprietary software. Requires a valid API key from the ProDeepLinks portal.