rn-prodeeplinks 0.0.1 → 0.0.3

package/README.md

@@ -4,7 +4,7 @@
 
 > ⚠️ **License Required**: This package requires a valid license key purchased from our portal. Without a license key, the package will not function.
 
-> ℹ️ **Versioning**: Current version is 0.0.1 (in-progress). It will move to 1.x after stable.
+> ℹ️ **Versioning**: Current version is 0.0.3 (in-progress). It will move to 1.x after stable.
 
 ## Features
 
@@ -130,6 +130,45 @@ const deepLink = new ProDeepLink({
 const result = await deepLink.getDeepLinkUrl();
 ```
 
+### Analytics & Tracking
+
+This SDK can optionally send deep link analytics events to our tracking service.
+
+- When a deep link is opened via React Native `Linking.getInitialURL()`, the SDK:
+  - Resolves the URL
+  - Collects device fingerprint data
+  - Sends an internal analytics event with the resolved short URL and fingerprint
+- When a deep link is resolved via the fingerprint API, the SDK:
+  - Resolves the URL from the server
+  - Sends the same internal analytics event with the short URL and fingerprint
+
+These internal events are handled by the SDK and are not part of the public API.
+
+You can also send custom tracking events manually after calling `init`:
+
+```typescript
+import {
+  trackAnalyticsEvent,
+  CustomDeepLinkAnalyticsEvent,
+} from 'rn-prodeeplinks';
+
+const event: CustomDeepLinkAnalyticsEvent = {
+  eventType: 'deeplink',
+  eventName: 'my_custom_event',
+  category: 'custom',
+  action: 'open',
+  label: 'My custom event',
+  properties: {
+    shortUrl: 'https://your-short-url',
+    foo: 'bar',
+  },
+};
+
+await trackAnalyticsEvent(event);
+```
+
+The license key provided to `init` is automatically included in the request headers. You do not need to include the license key in the analytics event payload.
+
 ## API Reference
 
 ### Functions
@@ -182,6 +221,26 @@ getDeepLink((url) => {
 });
 ```
 
+#### `trackAnalyticsEvent(event: CustomDeepLinkAnalyticsEvent): Promise<any>`
+
+Sends a custom analytics event to the tracking service.
+
+`init()` must be called successfully first; the stored license key from `init` is sent in the request headers.
+
+**Parameters:**
+- `event` (CustomDeepLinkAnalyticsEvent, required): Event describing what happened. You can use any `eventName` and add any custom properties.
+
+**Example:**
+```typescript
+await trackAnalyticsEvent({
+  eventType: 'deeplink',
+  eventName: 'button_click',
+  properties: {
+    buttonId: 'cta_start',
+  },
+});
+```
+
 #### `isReady(): boolean`
 
 Checks if the package has been initialized with a license key.
@@ -234,24 +293,16 @@ License keys are **NOT FREE**. You must:
 - Invalid or expired license keys will result in API errors
 - License keys cannot be shared or reused without authorization
 
-### Custom License Validate API (Optional)
-For environments with a custom auth API, the license validate endpoint is:
-
-POST {{base_url}}{{api_prefix}}/custom-deep-link/license/validate
+### Custom License Validation (Optional)
 
-Example (Postman):
+In most cases you should rely on the built‑in license validation handled by this SDK.  
+If you have your own backend that integrates with our license service, you can:
 
-```
-POST '{{base_url}}{{api_prefix}}/custom-deep-link/license/validate'
-  --header 'Content-Type: application/json'
-  --body '{
-    "licenseKey": "{{license_key}}",
-    "domain": "acme.com",
-    "ipAddress": "103.21.149.10"
-  }'
-```
+- Call your backend from your app
+- Let your backend talk to our license service
+- Use the result in your own business logic
 
-This package exposes a helper to call this endpoint if needed. It does not interfere with the main deep link resolution flow.
+The exact backend endpoint and payload are specific to your environment and are intentionally not exposed in this README.
 
 ## Error Handling
 

package/lib/api.d.ts

@@ -20,5 +20,5 @@ export declare function validateLicenseInit(licenseKey: string): Promise<{
     status?: number;
     data?: LicenseValidationApiResponse;
 }>;
-export declare function matchFingerprintCustom(payload: FingerprintMatchPayload, baseUrl?: string): Promise<FingerprintMatchResponse>;
-export declare function trackCustomDeepLinkEvent(event: CustomDeepLinkAnalyticsEvent): Promise<any>;
+export declare function matchFingerprintCustom(payload: FingerprintMatchPayload, baseUrl?: string, licenseKey?: string): Promise<FingerprintMatchResponse>;
+export declare function trackCustomDeepLinkEvent(event: CustomDeepLinkAnalyticsEvent, licenseKey?: string): Promise<any>;

package/lib/api.js

@@ -26,7 +26,7 @@ async function fetchDeepLinkUrl(licenseKey, fingerprint, apiEndpoint, timeout =
             };
         }
         const PACKAGE_NAME = 'react-native-pro-deeplink';
-        const PACKAGE_VERSION = '0.0.1';
+        const PACKAGE_VERSION = '0.0.3';
         const payload = {
             licenseKey,
             fingerprint: fingerprint,
@@ -39,13 +39,14 @@ async function fetchDeepLinkUrl(licenseKey, fingerprint, apiEndpoint, timeout =
         const timeoutId = setTimeout(() => controller.abort(), timeout);
         try {
             const PACKAGE_NAME = 'react-native-pro-deeplink';
-            const PACKAGE_VERSION = '0.0.1';
+            const PACKAGE_VERSION = '0.0.3';
             const response = await fetch(endpoint, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
                     'X-Package-Name': PACKAGE_NAME,
                     'X-Package-Version': PACKAGE_VERSION,
+                    'x-license-key': licenseKey,
                 },
                 body: JSON.stringify(payload),
                 signal: controller.signal,
@@ -129,7 +130,10 @@ async function validateLicenseCustom(licenseKey, opts) {
         };
         const res = await fetch(endpoint, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: {
+                'Content-Type': 'application/json',
+                'x-license-key': licenseKey,
+            },
             body: JSON.stringify(body),
         });
         const json = (await res.json().catch(() => ({})));
@@ -168,7 +172,7 @@ async function validateLicenseInit(licenseKey) {
         };
     }
 }
-async function matchFingerprintCustom(payload, baseUrl) {
+async function matchFingerprintCustom(payload, baseUrl, licenseKey) {
     try {
         const base = (baseUrl || CUSTOM_API_BASE_URL).trim().replace(/\/+$/, '');
         const endpoint = `${base}/custom-deep-link/fingerprint/match`;
@@ -176,6 +180,7 @@ async function matchFingerprintCustom(payload, baseUrl) {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
+                ...(licenseKey ? { 'x-license-key': licenseKey } : {}),
             },
             body: JSON.stringify(payload),
         });
@@ -190,12 +195,13 @@ async function matchFingerprintCustom(payload, baseUrl) {
         };
     }
 }
-async function trackCustomDeepLinkEvent(event) {
+async function trackCustomDeepLinkEvent(event, licenseKey) {
     try {
         const res = await fetch(ANALYTICS_ENDPOINT, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
+                ...(licenseKey ? { 'x-license-key': licenseKey } : {}),
             },
             body: JSON.stringify(event),
         });

package/lib/fingerprint.js

@@ -26,8 +26,10 @@ async function generateDeviceFingerprint() {
         const isRooted = react_native_1.Platform.OS === 'android'
             ? (await (react_native_device_info_1.default.isDeviceRooted?.() ?? false))
             : false;
-        // Get locale info
-        const locale = react_native_device_info_1.default.getDeviceLocale?.() || Intl.DateTimeFormat().resolvedOptions().locale;
+        const deviceLocales = react_native_device_info_1.default.getDeviceLocales?.();
+        const locale = (Array.isArray(deviceLocales) && deviceLocales.length > 0
+            ? deviceLocales[0]
+            : Intl.DateTimeFormat().resolvedOptions().locale) || 'en';
         const language = (locale || '').split('-')[0] || 'en';
         const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
         // Get network info

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { InitConfig, DeepLinkResponse } from './types';
+import { InitConfig, DeepLinkResponse, CustomDeepLinkAnalyticsEvent } from './types';
 /**
  * Initialize the deep link package with license key
  * This must be called before using getDeepLink()
@@ -53,7 +53,8 @@ export declare function isReady(): boolean;
  * Useful for testing or logout scenarios
  */
 export declare function reset(): void;
-export type { InitConfig, DeepLinkResponse } from './types';
+export declare function trackAnalyticsEvent(event: CustomDeepLinkAnalyticsEvent): Promise<any>;
+export type { InitConfig, DeepLinkResponse, CustomDeepLinkAnalyticsEvent } from './types';
 export declare class ProDeepLink {
     private licenseKey;
     constructor(config: InitConfig);
@@ -64,5 +65,6 @@ declare const _default: {
     getDeepLink: typeof getDeepLink;
     isReady: typeof isReady;
     reset: typeof reset;
+    trackAnalyticsEvent: typeof trackAnalyticsEvent;
 };
 export default _default;

package/lib/index.js

@@ -5,6 +5,7 @@ exports.init = init;
 exports.getDeepLink = getDeepLink;
 exports.isReady = isReady;
 exports.reset = reset;
+exports.trackAnalyticsEvent = trackAnalyticsEvent;
 const fingerprint_1 = require("./fingerprint");
 const api_1 = require("./api");
 const license_1 = require("./license");
@@ -60,6 +61,25 @@ async function init(config) {
         };
     }
 }
+async function trackDeepLinkResolved(url, source, fingerprint) {
+    const event = {
+        eventType: 'deeplink',
+        eventName: 'pro_track',
+        category: source,
+        action: 'open',
+        label: url,
+        properties: {
+            shortUrl: url,
+            source,
+            fingerprint,
+        },
+    };
+    try {
+        await trackAnalyticsEvent(event);
+    }
+    catch {
+    }
+}
 /**
  * Get deep link URL from server
  * This function automatically handles device fingerprinting internally
@@ -95,6 +115,12 @@ async function getDeepLink(callback) {
         // First: try to read deep link via Linking (if app opened by URL)
         const initialUrl = await react_native_1.Linking.getInitialURL();
         if (initialUrl) {
+            try {
+                const fingerprint = await (0, fingerprint_1.generateDeviceFingerprint)();
+                await trackDeepLinkResolved(initialUrl, 'linking', fingerprint);
+            }
+            catch {
+            }
             if (callback)
                 callback(initialUrl);
             return { success: true, url: initialUrl };
@@ -104,6 +130,13 @@ async function getDeepLink(callback) {
         // Fetch deep link URL from API with retry mechanism
         const result = await (0, api_1.fetchDeepLinkUrlWithRetry)(storedLicenseKey, fingerprint, 3, // retry attempts
         DEFAULT_API_ENDPOINT);
+        if (result.success && result.url) {
+            try {
+                await trackDeepLinkResolved(result.url, 'api', fingerprint);
+            }
+            catch {
+            }
+        }
         // Call callback if provided and result is successful
         if (callback && result.success && result.url) {
             callback(result.url);
@@ -136,6 +169,16 @@ function reset() {
     storedLicenseKey = null;
     isInitialized = false;
 }
+async function trackAnalyticsEvent(event) {
+    if (!isInitialized || !storedLicenseKey) {
+        return {
+            success: false,
+            error: 'Please call init() first with your license key',
+        };
+    }
+    const { licenseKey: _ignored, ...payload } = event;
+    return (0, api_1.trackCustomDeepLinkEvent)(payload, storedLicenseKey);
+}
 // Keep backward compatibility - export class for advanced users (optional)
 class ProDeepLink {
     constructor(config) {
@@ -154,9 +197,17 @@ class ProDeepLink {
             };
         }
         const fingerprint = await (0, fingerprint_1.generateDeviceFingerprint)();
-        return await (0, api_1.fetchDeepLinkUrlWithRetry)(this.licenseKey, fingerprint, 3, DEFAULT_API_ENDPOINT);
+        const result = await (0, api_1.fetchDeepLinkUrlWithRetry)(this.licenseKey, fingerprint, 3, DEFAULT_API_ENDPOINT);
+        if (result.success && result.url) {
+            try {
+                await trackDeepLinkResolved(result.url, 'api', fingerprint);
+            }
+            catch {
+            }
+        }
+        return result;
     }
 }
 exports.ProDeepLink = ProDeepLink;
 // Export default
-exports.default = { init, getDeepLink, isReady, reset };
+exports.default = { init, getDeepLink, isReady, reset, trackAnalyticsEvent };

package/lib/types.d.ts

@@ -70,7 +70,7 @@ export interface CustomDeepLinkAnalyticsDeviceInfo {
     [key: string]: any;
 }
 export interface CustomDeepLinkAnalyticsEvent {
-    licenseKey: string;
+    licenseKey?: string;
     eventType: string;
     eventName: string;
     category?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-prodeeplinks",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Secure deep linking package with license key validation and device fingerprinting for React Native",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",