expo-facebook-analytics 1.0.0

package/README.md

@@ -0,0 +1,242 @@
+# expo-facebook-analytics
+
+High-performance Facebook Analytics for React Native using [Nitro Modules](https://github.com/mrousavy/nitro).
+
+## Features
+
+- Direct native Facebook SDK integration via Nitro Modules (zero-copy bridge)
+- Full event logging, user identity management, and device identifier access
+- Expo config plugin for automatic native setup
+- TypeScript-first with predefined event and parameter constants
+- iOS 13+ and Android SDK 21+
+
+## Installation
+
+```sh
+bun add expo-facebook-analytics react-native-nitro-modules
+```
+
+or
+
+```sh
+npm install expo-facebook-analytics react-native-nitro-modules
+```
+
+### Peer Dependencies
+
+- `react-native` >= 0.71
+- `react-native-nitro-modules` >= 0.33.2
+- `expo` >= 55.0.4 _(optional, for config plugin)_
+
+### iOS
+
+```sh
+cd ios && pod install
+```
+
+### Android
+
+No additional steps required — Gradle handles the Facebook SDK dependency automatically.
+
+## Expo Setup
+
+Add the plugin to your `app.json` / `app.config.js`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-facebook-analytics",
+        {
+          "appID": "YOUR_FACEBOOK_APP_ID",
+          "clientToken": "YOUR_FACEBOOK_CLIENT_TOKEN",
+          "displayName": "Your App Name"
+        }
+      ]
+    ]
+  }
+}
+```
+
+### Plugin Options
+
+| Option                          | Type                  | Default       | Description                                |
+| ------------------------------- | --------------------- | ------------- | ------------------------------------------ |
+| `appID`                         | `string`              | **required**  | Facebook App ID                            |
+| `clientToken`                   | `string`              | **required**  | Facebook Client Token                      |
+| `displayName`                   | `string`              | App name      | Display name for Facebook                  |
+| `scheme`                        | `string`              | `fb{appID}`   | URL scheme for deep linking                |
+| `isAutoInitEnabled`             | `boolean`             | `true`        | Auto-initialize Facebook SDK               |
+| `autoLogAppEventsEnabled`       | `boolean`             | `true`        | Automatically log app events               |
+| `advertiserIDCollectionEnabled` | `boolean`             | `true`        | Enable advertiser ID collection            |
+| `iosUserTrackingPermission`     | `string` \| `false`   | ATT prompt    | Custom tracking permission text or disable |
+
+### Manual Native Setup
+
+If you're not using Expo, refer to the [Facebook SDK documentation](https://developers.facebook.com/docs/app-events/getting-started-app-events-android/) for manual iOS and Android configuration.
+
+## Usage
+
+### Log Events
+
+```typescript
+import { logEvent, logPurchase, AppEvents, AppEventParams } from 'expo-facebook-analytics';
+
+// Simple event
+logEvent(AppEvents.ViewedContent);
+
+// Event with a numeric value
+logEvent(AppEvents.Searched, 1);
+
+// Event with parameters
+logEvent(AppEvents.AddedToCart, {
+  [AppEventParams.ContentID]: 'product-123',
+  [AppEventParams.ContentType]: 'product',
+  [AppEventParams.Currency]: 'USD',
+});
+
+// Event with value and parameters
+logEvent(AppEvents.Purchased, 29.99, {
+  [AppEventParams.Currency]: 'USD',
+  [AppEventParams.NumItems]: 2,
+});
+
+// Log a purchase
+logPurchase(29.99, 'USD', {
+  [AppEventParams.ContentID]: 'product-123',
+});
+
+// Log push notification open
+logPushNotificationOpen({ campaign: 'summer-sale' });
+```
+
+### User Identity
+
+```typescript
+import { setUserID, getUserID, clearUserID, setUserData } from 'expo-facebook-analytics';
+
+// Set user ID for analytics
+setUserID('user-123');
+
+// Get current user ID
+const userId = getUserID();
+
+// Clear user ID
+clearUserID();
+
+// Set user data for advanced matching
+setUserData({
+  email: 'user@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  gender: 'm',
+  city: 'San Francisco',
+  state: 'CA',
+  country: 'US',
+});
+```
+
+### Device Identifiers
+
+```typescript
+import { getAnonymousID, getAdvertiserID } from 'expo-facebook-analytics';
+
+const anonId = await getAnonymousID();
+const advertiserId = await getAdvertiserID(); // IDFA on iOS, AAID on Android
+```
+
+### Configuration
+
+```typescript
+import { setFlushBehavior, flush, setPushNotificationsDeviceToken, setPushNotificationsRegistrationId } from 'expo-facebook-analytics';
+
+// Control event batching: 'auto' (default) or 'explicit_only'
+setFlushBehavior('explicit_only');
+
+// Manually flush queued events
+flush();
+
+// Push notification tokens
+setPushNotificationsDeviceToken(apnsToken);       // iOS
+setPushNotificationsRegistrationId(fcmToken);     // Android
+```
+
+## API Reference
+
+### Event Logging
+
+| Function                    | Description                          |
+| --------------------------- | ------------------------------------ |
+| `logEvent(name, ...args)`   | Log a custom or predefined event     |
+| `logPurchase(amount, currency, params?)` | Log a purchase event      |
+| `logPushNotificationOpen(payload?)` | Log a push notification open  |
+
+### User Identity
+
+| Function                | Description                        |
+| ----------------------- | ---------------------------------- |
+| `setUserID(id)`         | Set the user ID for analytics      |
+| `clearUserID()`         | Clear the current user ID          |
+| `getUserID()`           | Get the current user ID            |
+| `setUserData(data)`     | Set user data for advanced matching|
+
+### Device Identifiers
+
+| Function              | Description                                 |
+| --------------------- | ------------------------------------------- |
+| `getAnonymousID()`    | Get the anonymous device ID                 |
+| `getAdvertiserID()`   | Get IDFA (iOS) or AAID (Android)            |
+
+### Configuration
+
+| Function                              | Description                        |
+| ------------------------------------- | ---------------------------------- |
+| `setFlushBehavior(behavior)`          | Set event flush behavior           |
+| `flush()`                             | Flush queued events immediately    |
+| `setPushNotificationsDeviceToken(t)`  | Set APNs push token (iOS)         |
+| `setPushNotificationsRegistrationId(id)` | Set FCM registration ID (Android) |
+
+## Predefined Constants
+
+### AppEvents
+
+`AchievedLevel`, `AdClick`, `AdImpression`, `AddedPaymentInfo`, `AddedToCart`, `AddedToWishlist`, `CompletedRegistration`, `CompletedTutorial`, `Contact`, `CustomizeProduct`, `Donate`, `FindLocation`, `InitiatedCheckout`, `Purchased`, `Rated`, `Schedule`, `Searched`, `SpentCredits`, `StartTrial`, `SubmitApplication`, `Subscribe`, `UnlockedAchievement`, `ViewedContent`
+
+### AppEventParams
+
+`AddType`, `Content`, `ContentID`, `ContentType`, `Currency`, `Description`, `Level`, `MaxRatingValue`, `NumItems`, `OrderId`, `PaymentInfoAvailable`, `RegistrationMethod`, `SearchString`, `Success`, `ValueNo`, `ValueYes`
+
+## Types
+
+```typescript
+type Params = { [key: string]: string | number };
+
+type UserData = Readonly<{
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  phone?: string;
+  dateOfBirth?: string;
+  gender?: 'm' | 'f';
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+}>;
+
+type AppEventsFlushBehavior = 'auto' | 'explicit_only';
+```
+
+## Requirements
+
+| Platform | Minimum Version |
+| -------- | --------------- |
+| iOS      | 13.0            |
+| Android  | SDK 21          |
+
+Native SDKs: Facebook SDK ~17.0
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,60 @@
+buildscript {
+    ext.safeExtGet = {prop, fallback ->
+        rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+    }
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.2.0")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22")
+    }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def nitrogenAutolinking = file("nitrogen/generated/android/NitroFBAnalytics-autolinking.gradle")
+if (nitrogenAutolinking.exists()) {
+    apply from: nitrogenAutolinking
+}
+
+android {
+    namespace 'com.nitrofbanalytics'
+    compileSdkVersion safeExtGet('compileSdkVersion', 34)
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 21)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+    }
+
+    sourceSets {
+        main {
+            java.srcDirs += [
+                'src/main/java',
+                'nitrogen/generated/android/kotlin'
+            ]
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    kotlinOptions {
+        jvmTarget = '1.8'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-native:+'
+    implementation 'com.margelo.nitro:nitro-modules:+'
+    implementation 'com.facebook.android:facebook-android-sdk:17.+'
+}

package/android/src/main/java/com/nitrofbanalytics/HybridFacebookAnalytics.kt

@@ -0,0 +1,139 @@
+package com.nitrofbanalytics
+
+import android.os.Bundle
+import com.facebook.FacebookSdk
+import com.facebook.appevents.AppEventsConstants
+import com.facebook.appevents.AppEventsLogger
+import com.facebook.internal.AttributionIdentifiers
+import com.margelo.nitro.core.Promise
+import java.math.BigDecimal
+import java.util.Currency
+
+class HybridFacebookAnalytics : HybridFacebookAnalyticsSpec() {
+
+    private val logger: AppEventsLogger by lazy {
+        AppEventsLogger.newLogger(FacebookSdk.getApplicationContext())
+    }
+
+    // region Event Logging
+
+    override fun logEvent(eventName: String, valueToSum: Double, params: Map<String, String>) {
+        val bundle = mapToBundle(params)
+        logger.logEvent(eventName, valueToSum, bundle)
+    }
+
+    override fun logEventWithoutParams(eventName: String, valueToSum: Double) {
+        if (valueToSum != 0.0) {
+            logger.logEvent(eventName, valueToSum)
+        } else {
+            logger.logEvent(eventName)
+        }
+    }
+
+    override fun logPurchase(amount: Double, currency: String, params: Map<String, String>) {
+        val bundle = mapToBundle(params)
+        logger.logPurchase(
+            BigDecimal.valueOf(amount),
+            Currency.getInstance(currency),
+            bundle
+        )
+    }
+
+    override fun logPushNotificationOpen(payload: Map<String, String>) {
+        val bundle = mapToBundle(payload)
+        logger.logPushNotificationOpen(bundle)
+    }
+
+    // endregion
+
+    // region User Identity
+
+    override fun setUserID(userID: String) {
+        AppEventsLogger.setUserID(userID)
+    }
+
+    override fun clearUserID() {
+        AppEventsLogger.clearUserID()
+    }
+
+    override fun getUserID(): String? {
+        return AppEventsLogger.getUserID()
+    }
+
+    override fun setUserData(
+        email: String?,
+        firstName: String?,
+        lastName: String?,
+        phone: String?,
+        dateOfBirth: String?,
+        gender: String?,
+        city: String?,
+        state: String?,
+        zip: String?,
+        country: String?
+    ) {
+        AppEventsLogger.setUserData(
+            email, firstName, lastName, phone,
+            dateOfBirth, gender, city, state, zip, country
+        )
+    }
+
+    // endregion
+
+    // region Device Identifiers
+
+    override fun getAnonymousID(): Promise<String?> {
+        return Promise.resolved(logger.anonymousAppDeviceGUID)
+    }
+
+    override fun getAdvertiserID(): Promise<String?> {
+        return try {
+            val context = FacebookSdk.getApplicationContext()
+            val identifiers = AttributionIdentifiers.getAttributionIdentifiers(context)
+            Promise.resolved(identifiers?.androidAdvertiserId)
+        } catch (e: Exception) {
+            Promise.resolved(null)
+        }
+    }
+
+    // endregion
+
+    // region Configuration
+
+    override fun setFlushBehavior(flushBehavior: String) {
+        when (flushBehavior) {
+            "explicit_only" -> AppEventsLogger.setFlushBehavior(AppEventsLogger.FlushBehavior.EXPLICIT_ONLY)
+            else -> AppEventsLogger.setFlushBehavior(AppEventsLogger.FlushBehavior.AUTO)
+        }
+    }
+
+    override fun flush() {
+        logger.flush()
+    }
+
+    // endregion
+
+    // region Push Notifications
+
+    override fun setPushNotificationsDeviceToken(token: String) {
+        // No-op on Android — use setPushNotificationsRegistrationId instead
+    }
+
+    override fun setPushNotificationsRegistrationId(registrationId: String) {
+        AppEventsLogger.setPushNotificationsRegistrationId(registrationId)
+    }
+
+    // endregion
+
+    // region Helpers
+
+    private fun mapToBundle(map: Map<String, String>): Bundle {
+        val bundle = Bundle()
+        for ((key, value) in map) {
+            bundle.putString(key, value)
+        }
+        return bundle
+    }
+
+    // endregion
+}

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require("./plugin/build").default;

package/expo-facebook-analytics.podspec

@@ -0,0 +1,31 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+nitrogen_autolinking = File.join(__dir__, 'nitrogen', 'generated', 'ios', 'NitroFBAnalytics+autolinking.rb')
+
+Pod::Spec.new do |s|
+  s.name         = 'expo-facebook-analytics'
+  s.version      = package['version']
+  s.summary      = package['description']
+  s.homepage     = 'https://github.com/user/expo-facebook-analytics'
+  s.license      = package['license']
+  s.author       = 'expo-facebook-analytics contributors'
+  s.source       = { :git => '.', :tag => s.version.to_s }
+  s.platforms    = { :ios => '13.0' }
+  s.module_name  = 'NitroFBAnalytics'
+
+  s.source_files = [
+    'ios/**/*.{swift,h,hpp,m,mm,cpp}',
+  ]
+
+  s.dependency 'React-Core'
+  s.dependency 'FBSDKCoreKit', '~> 17.0'
+
+  s.frameworks = ['AdSupport']
+
+  if File.exist?(nitrogen_autolinking)
+    load nitrogen_autolinking
+    add_nitrogen_files(s)
+  end
+end

package/ios/HybridFacebookAnalytics.swift

@@ -0,0 +1,135 @@
+import Foundation
+import NitroModules
+import FBSDKCoreKit
+import AdSupport
+
+class HybridFacebookAnalytics: HybridFacebookAnalyticsSpec {
+
+    // MARK: - Event Logging
+
+    func logEvent(eventName: String, valueToSum: Double, params: [String: String]) throws {
+        let fbParams: [AppEvents.ParameterName: Any] = params.reduce(into: [:]) { result, pair in
+            result[AppEvents.ParameterName(pair.key)] = pair.value
+        }
+        AppEvents.shared.logEvent(
+            AppEvents.Name(eventName),
+            valueToSum: valueToSum,
+            parameters: fbParams
+        )
+    }
+
+    func logEventWithoutParams(eventName: String, valueToSum: Double) throws {
+        if valueToSum != 0 {
+            AppEvents.shared.logEvent(
+                AppEvents.Name(eventName),
+                valueToSum: valueToSum
+            )
+        } else {
+            AppEvents.shared.logEvent(AppEvents.Name(eventName))
+        }
+    }
+
+    func logPurchase(amount: Double, currency: String, params: [String: String]) throws {
+        let fbParams: [AppEvents.ParameterName: Any] = params.reduce(into: [:]) { result, pair in
+            result[AppEvents.ParameterName(pair.key)] = pair.value
+        }
+        AppEvents.shared.logPurchase(amount: amount, currency: currency, parameters: fbParams)
+    }
+
+    func logPushNotificationOpen(payload: [String: String]) throws {
+        let nsPayload: [String: Any] = payload.reduce(into: [:]) { result, pair in
+            result[pair.key] = pair.value
+        }
+        AppEvents.shared.logPushNotificationOpen(payload: nsPayload)
+    }
+
+    // MARK: - User Identity
+
+    func setUserID(userID: String) throws {
+        AppEvents.shared.userID = userID
+    }
+
+    func clearUserID() throws {
+        AppEvents.shared.userID = nil
+    }
+
+    func getUserID() throws -> String? {
+        return AppEvents.shared.userID
+    }
+
+    func setUserData(
+        email: String?,
+        firstName: String?,
+        lastName: String?,
+        phone: String?,
+        dateOfBirth: String?,
+        gender: String?,
+        city: String?,
+        state: String?,
+        zip: String?,
+        country: String?
+    ) throws {
+        AppEvents.shared.setUser(
+            email: email,
+            firstName: firstName,
+            lastName: lastName,
+            phone: phone,
+            dateOfBirth: dateOfBirth,
+            gender: gender,
+            city: city,
+            state: state,
+            zip: zip,
+            country: country
+        )
+    }
+
+    // MARK: - Device Identifiers
+
+    func getAnonymousID() throws -> Promise<String?> {
+        return Promise.resolved(withResult: AppEvents.shared.anonymousID)
+    }
+
+    func getAdvertiserID() throws -> Promise<String?> {
+        let idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
+        if idfa == "00000000-0000-0000-0000-000000000000" {
+            return Promise.resolved(withResult: nil)
+        }
+        return Promise.resolved(withResult: idfa)
+    }
+
+    // MARK: - Configuration
+
+    func setFlushBehavior(flushBehavior: String) throws {
+        switch flushBehavior {
+        case "explicit_only":
+            AppEvents.shared.flushBehavior = .explicitOnly
+        default:
+            AppEvents.shared.flushBehavior = .auto
+        }
+    }
+
+    func flush() throws {
+        AppEvents.shared.flush()
+    }
+
+    // MARK: - Push Notifications
+
+    func setPushNotificationsDeviceToken(token: String) throws {
+        // Token comes as a hex string — convert back to raw Data
+        let hex = token.replacingOccurrences(of: " ", with: "")
+        var data = Data()
+        var index = hex.startIndex
+        while index < hex.endIndex {
+            let nextIndex = hex.index(index, offsetBy: 2)
+            if let byte = UInt8(hex[index..<nextIndex], radix: 16) {
+                data.append(byte)
+            }
+            index = nextIndex
+        }
+        AppEvents.shared.setPushNotificationsDeviceToken(data)
+    }
+
+    func setPushNotificationsRegistrationId(registrationId: String) throws {
+        // No-op on iOS — this is an Android-only method
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,58 @@
+import type { AppEventsFlushBehavior, Params, UserData } from "./types";
+export type { AppEventsFlushBehavior, Params, UserData } from "./types";
+export { AppEventParams, AppEvents } from "./types";
+/**
+ * Log a custom or predefined app event.
+ * @param eventName - Event name (use AppEvents constants for predefined events)
+ * @param args - Optional valueToSum (number) and/or params object
+ */
+export declare function logEvent(eventName: string, ...args: Array<number | Params>): void;
+/**
+ * Log a purchase event.
+ */
+export declare function logPurchase(purchaseAmount: number, currencyCode: string, parameters?: Params): void;
+/**
+ * Log a push notification open event.
+ */
+export declare function logPushNotificationOpen(payload?: Record<string, string | number>): void;
+/**
+ * Set the user ID for analytics association.
+ */
+export declare function setUserID(userID: string | null): void;
+/**
+ * Clear the current user ID.
+ */
+export declare function clearUserID(): void;
+/**
+ * Get the current user ID.
+ */
+export declare function getUserID(): string | undefined;
+/**
+ * Set user data for advanced matching.
+ */
+export declare function setUserData(userData: UserData): void;
+/**
+ * Get the anonymous device ID.
+ */
+export declare function getAnonymousID(): Promise<string | undefined>;
+/**
+ * Get the advertiser ID (IDFA on iOS, AAID on Android).
+ */
+export declare function getAdvertiserID(): Promise<string | undefined>;
+/**
+ * Set the flush behavior for event batching.
+ * @param flushBehavior - 'auto' or 'explicit_only'
+ */
+export declare function setFlushBehavior(flushBehavior: AppEventsFlushBehavior): void;
+/**
+ * Flush all queued events to Facebook immediately.
+ */
+export declare function flush(): void;
+/**
+ * Set the push notification device token (iOS).
+ */
+export declare function setPushNotificationsDeviceToken(deviceToken: string): void;
+/**
+ * Set the push notification registration ID (Android/FCM).
+ */
+export declare function setPushNotificationsRegistrationId(registrationId: string): void;