expo-facebook-analytics 1.0.0

package/plugin/build/withFacebookAnalyticsAndroid.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAndroidPermissions = exports.withFacebookManifest = exports.withFacebookAppIdString = void 0;
+const config_plugins_1 = require("@expo/config-plugins");
+const withFacebookAppIdString = (config, props) => {
+    return (0, config_plugins_1.withStringsXml)(config, (mod) => {
+        const stringItems = mod.modResults.resources.string ?? [];
+        const setString = (name, value) => {
+            const existing = stringItems.findIndex((item) => item.$.name === name);
+            const entry = {
+                $: { name, translatable: "false" },
+                _: value,
+            };
+            if (existing >= 0) {
+                stringItems[existing] = entry;
+            }
+            else {
+                stringItems.push(entry);
+            }
+        };
+        setString("facebook_app_id", props.appID);
+        setString("facebook_client_token", props.clientToken);
+        setString("facebook_login_protocol_scheme", props.scheme);
+        mod.modResults.resources.string = stringItems;
+        return mod;
+    });
+};
+exports.withFacebookAppIdString = withFacebookAppIdString;
+const withFacebookManifest = (config, props) => {
+    return (0, config_plugins_1.withAndroidManifest)(config, (mod) => {
+        const mainApplication = config_plugins_1.AndroidConfig.Manifest.getMainApplicationOrThrow(mod.modResults);
+        // Add meta-data entries
+        if (!mainApplication["meta-data"]) {
+            mainApplication["meta-data"] = [];
+        }
+        const metaData = mainApplication["meta-data"];
+        const setMetaData = (name, value) => {
+            const existing = metaData.findIndex((item) => item.$["android:name"] === name);
+            const entry = {
+                $: {
+                    "android:name": name,
+                    "android:value": value,
+                },
+            };
+            if (existing >= 0) {
+                metaData[existing] = entry;
+            }
+            else {
+                metaData.push(entry);
+            }
+        };
+        setMetaData("com.facebook.sdk.ApplicationId", "@string/facebook_app_id");
+        setMetaData("com.facebook.sdk.ClientToken", "@string/facebook_client_token");
+        setMetaData("com.facebook.sdk.ApplicationName", props.displayName);
+        setMetaData("com.facebook.sdk.AutoInitEnabled", String(props.isAutoInitEnabled));
+        setMetaData("com.facebook.sdk.AutoLogAppEventsEnabled", String(props.autoLogAppEventsEnabled));
+        setMetaData("com.facebook.sdk.AdvertiserIDCollectionEnabled", String(props.advertiserIDCollectionEnabled));
+        return mod;
+    });
+};
+exports.withFacebookManifest = withFacebookManifest;
+const withAndroidPermissions = (config, _props) => {
+    return config_plugins_1.AndroidConfig.Permissions.withPermissions(config, [
+        "android.permission.INTERNET",
+    ]);
+};
+exports.withAndroidPermissions = withAndroidPermissions;

package/plugin/build/withFacebookAnalyticsIOS.d.ts

@@ -0,0 +1,16 @@
+import { type ConfigPlugin } from "@expo/config-plugins";
+type ResolvedProps = {
+    appID: string;
+    clientToken: string;
+    displayName: string;
+    scheme: string;
+    isAutoInitEnabled: boolean;
+    autoLogAppEventsEnabled: boolean;
+    advertiserIDCollectionEnabled: boolean;
+    iosUserTrackingPermission?: string | false;
+};
+export declare const withFacebookIOS: ConfigPlugin<ResolvedProps>;
+export declare const withUserTrackingPermission: ConfigPlugin<ResolvedProps>;
+export declare const withFacebookAppDelegate: ConfigPlugin<ResolvedProps>;
+export declare const withSKAdNetworkIdentifiers: ConfigPlugin<string[]>;
+export {};

package/plugin/build/withFacebookAnalyticsIOS.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSKAdNetworkIdentifiers = exports.withFacebookAppDelegate = exports.withUserTrackingPermission = exports.withFacebookIOS = void 0;
+const config_plugins_1 = require("@expo/config-plugins");
+const withFacebookIOS = (config, props) => {
+    return (0, config_plugins_1.withInfoPlist)(config, (mod) => {
+        mod.modResults.FacebookAppID = props.appID;
+        mod.modResults.FacebookClientToken = props.clientToken;
+        mod.modResults.FacebookDisplayName = props.displayName;
+        mod.modResults.FacebookAutoInitEnabled = props.isAutoInitEnabled;
+        mod.modResults.FacebookAutoLogAppEventsEnabled =
+            props.autoLogAppEventsEnabled;
+        mod.modResults.FacebookAdvertiserIDCollectionEnabled =
+            props.advertiserIDCollectionEnabled;
+        // URL schemes
+        if (!mod.modResults.CFBundleURLTypes) {
+            mod.modResults.CFBundleURLTypes = [];
+        }
+        const fbSchemeEntry = mod.modResults.CFBundleURLTypes.find((entry) => entry.CFBundleURLSchemes?.includes(props.scheme));
+        if (!fbSchemeEntry) {
+            mod.modResults.CFBundleURLTypes.push({
+                CFBundleURLSchemes: [props.scheme],
+            });
+        }
+        // LSApplicationQueriesSchemes
+        const queriesSchemes = [
+            "fbapi",
+            "fb-messenger-api",
+            "fbauth2",
+            "fbshareextension",
+        ];
+        if (!mod.modResults.LSApplicationQueriesSchemes) {
+            mod.modResults.LSApplicationQueriesSchemes = [];
+        }
+        for (const scheme of queriesSchemes) {
+            if (!mod.modResults.LSApplicationQueriesSchemes.includes(scheme)) {
+                mod.modResults.LSApplicationQueriesSchemes.push(scheme);
+            }
+        }
+        return mod;
+    });
+};
+exports.withFacebookIOS = withFacebookIOS;
+const withUserTrackingPermission = (config, props) => {
+    if (props.iosUserTrackingPermission === false) {
+        return config;
+    }
+    return (0, config_plugins_1.withInfoPlist)(config, (mod) => {
+        mod.modResults.NSUserTrackingUsageDescription =
+            props.iosUserTrackingPermission ||
+                "This identifier will be used to deliver personalized ads to you.";
+        return mod;
+    });
+};
+exports.withUserTrackingPermission = withUserTrackingPermission;
+const withFacebookAppDelegate = (config, _props) => {
+    return (0, config_plugins_1.withAppDelegate)(config, (mod) => {
+        const contents = mod.modResults.contents;
+        // Add import
+        if (!contents.includes("#import <FBSDKCoreKit/FBSDKCoreKit.h>")) {
+            mod.modResults.contents = mod.modResults.contents.replace('#import "AppDelegate.h"', '#import "AppDelegate.h"\n#import <FBSDKCoreKit/FBSDKCoreKit.h>');
+        }
+        // Add didFinishLaunchingWithOptions hook
+        if (!contents.includes("FBSDKApplicationDelegate")) {
+            mod.modResults.contents = mod.modResults.contents.replace("self.initialProps = @{};", "self.initialProps = @{};\n  [[FBSDKApplicationDelegate sharedInstance] application:application didFinishLaunchingWithOptions:launchOptions];");
+        }
+        // Add openURL handler
+        if (!contents.includes("openURL:url options:options")) {
+            const openURLMethod = `
+
+- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
+  return [[FBSDKApplicationDelegate sharedInstance] application:application openURL:url options:options];
+}`;
+            mod.modResults.contents = mod.modResults.contents.replace(/@end\s*$/, `${openURLMethod}\n\n@end\n`);
+        }
+        return mod;
+    });
+};
+exports.withFacebookAppDelegate = withFacebookAppDelegate;
+const withSKAdNetworkIdentifiers = (config, identifiers) => {
+    return (0, config_plugins_1.withInfoPlist)(config, (mod) => {
+        if (!mod.modResults.SKAdNetworkItems) {
+            mod.modResults.SKAdNetworkItems = [];
+        }
+        const existing = new Set(mod.modResults.SKAdNetworkItems.map((item) => item.SKAdNetworkIdentifier));
+        for (const id of identifiers) {
+            if (!existing.has(id)) {
+                mod.modResults.SKAdNetworkItems.push({
+                    SKAdNetworkIdentifier: id,
+                });
+            }
+        }
+        return mod;
+    });
+};
+exports.withSKAdNetworkIdentifiers = withSKAdNetworkIdentifiers;

package/src/index.ts

@@ -0,0 +1,161 @@
+import { NitroModules } from "react-native-nitro-modules";
+import type { FacebookAnalytics as FacebookAnalyticsSpec } from "./specs/FacebookAnalytics.nitro";
+import type { AppEventsFlushBehavior, Params, UserData } from "./types";
+
+export type { AppEventsFlushBehavior, Params, UserData } from "./types";
+export { AppEventParams, AppEvents } from "./types";
+
+const NativeFBAnalytics =
+  NitroModules.createHybridObject<FacebookAnalyticsSpec>("FacebookAnalytics");
+
+/**
+ * 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 function logEvent(
+  eventName: string,
+  ...args: Array<number | Params>
+): void {
+  let valueToSum = 0;
+  let params: Params = {};
+
+  for (const arg of args) {
+    if (typeof arg === "number") {
+      valueToSum = arg;
+    } else if (typeof arg === "object") {
+      params = arg;
+    }
+  }
+
+  const stringParams: Record<string, string> = {};
+  for (const [key, value] of Object.entries(params)) {
+    stringParams[key] = String(value);
+  }
+
+  if (Object.keys(stringParams).length > 0) {
+    NativeFBAnalytics.logEvent(eventName, valueToSum, stringParams);
+  } else {
+    NativeFBAnalytics.logEventWithoutParams(eventName, valueToSum);
+  }
+}
+
+/**
+ * Log a purchase event.
+ */
+export function logPurchase(
+  purchaseAmount: number,
+  currencyCode: string,
+  parameters?: Params,
+): void {
+  const stringParams: Record<string, string> = {};
+  if (parameters) {
+    for (const [key, value] of Object.entries(parameters)) {
+      stringParams[key] = String(value);
+    }
+  }
+  NativeFBAnalytics.logPurchase(purchaseAmount, currencyCode, stringParams);
+}
+
+/**
+ * Log a push notification open event.
+ */
+export function logPushNotificationOpen(
+  payload?: Record<string, string | number>,
+): void {
+  const stringPayload: Record<string, string> = {};
+  if (payload) {
+    for (const [key, value] of Object.entries(payload)) {
+      stringPayload[key] = String(value);
+    }
+  }
+  NativeFBAnalytics.logPushNotificationOpen(stringPayload);
+}
+
+/**
+ * Set the user ID for analytics association.
+ */
+export function setUserID(userID: string | null): void {
+  if (userID === null) {
+    NativeFBAnalytics.clearUserID();
+  } else {
+    NativeFBAnalytics.setUserID(userID);
+  }
+}
+
+/**
+ * Clear the current user ID.
+ */
+export function clearUserID(): void {
+  NativeFBAnalytics.clearUserID();
+}
+
+/**
+ * Get the current user ID.
+ */
+export function getUserID(): string | undefined {
+  return NativeFBAnalytics.getUserID();
+}
+
+/**
+ * Set user data for advanced matching.
+ */
+export function setUserData(userData: UserData): void {
+  NativeFBAnalytics.setUserData(
+    userData.email,
+    userData.firstName,
+    userData.lastName,
+    userData.phone,
+    userData.dateOfBirth,
+    userData.gender,
+    userData.city,
+    userData.state,
+    userData.zip,
+    userData.country,
+  );
+}
+
+/**
+ * Get the anonymous device ID.
+ */
+export function getAnonymousID(): Promise<string | undefined> {
+  return NativeFBAnalytics.getAnonymousID();
+}
+
+/**
+ * Get the advertiser ID (IDFA on iOS, AAID on Android).
+ */
+export function getAdvertiserID(): Promise<string | undefined> {
+  return NativeFBAnalytics.getAdvertiserID();
+}
+
+/**
+ * Set the flush behavior for event batching.
+ * @param flushBehavior - 'auto' or 'explicit_only'
+ */
+export function setFlushBehavior(flushBehavior: AppEventsFlushBehavior): void {
+  NativeFBAnalytics.setFlushBehavior(flushBehavior);
+}
+
+/**
+ * Flush all queued events to Facebook immediately.
+ */
+export function flush(): void {
+  NativeFBAnalytics.flush();
+}
+
+/**
+ * Set the push notification device token (iOS).
+ */
+export function setPushNotificationsDeviceToken(deviceToken: string): void {
+  NativeFBAnalytics.setPushNotificationsDeviceToken(deviceToken);
+}
+
+/**
+ * Set the push notification registration ID (Android/FCM).
+ */
+export function setPushNotificationsRegistrationId(
+  registrationId: string,
+): void {
+  NativeFBAnalytics.setPushNotificationsRegistrationId(registrationId);
+}

package/src/specs/FacebookAnalytics.nitro.ts

@@ -0,0 +1,47 @@
+import type { HybridObject } from "react-native-nitro-modules";
+
+export interface FacebookAnalytics
+  extends HybridObject<{ ios: "swift"; android: "kotlin" }> {
+  // Event logging
+  logEvent(
+    eventName: string,
+    valueToSum: number,
+    params: Record<string, string>,
+  ): void;
+  logEventWithoutParams(eventName: string, valueToSum: number): void;
+  logPurchase(
+    amount: number,
+    currency: string,
+    params: Record<string, string>,
+  ): void;
+  logPushNotificationOpen(payload: Record<string, string>): void;
+
+  // User identity
+  setUserID(userID: string): void;
+  clearUserID(): void;
+  getUserID(): string | undefined;
+  setUserData(
+    email: string | undefined,
+    firstName: string | undefined,
+    lastName: string | undefined,
+    phone: string | undefined,
+    dateOfBirth: string | undefined,
+    gender: string | undefined,
+    city: string | undefined,
+    state: string | undefined,
+    zip: string | undefined,
+    country: string | undefined,
+  ): void;
+
+  // Device identifiers
+  getAnonymousID(): Promise<string | undefined>;
+  getAdvertiserID(): Promise<string | undefined>;
+
+  // Configuration
+  setFlushBehavior(flushBehavior: string): void;
+  flush(): void;
+
+  // Push notification tokens
+  setPushNotificationsDeviceToken(token: string): void;
+  setPushNotificationsRegistrationId(registrationId: string): void;
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+export type AppEventsFlushBehavior = "auto" | "explicit_only";
+
+export type Params = { [key: string]: string | number };
+
+export type UserData = Readonly<{
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  phone?: string;
+  dateOfBirth?: string;
+  gender?: "m" | "f";
+  city?: string;
+  state?: string;
+  zip?: string;
+  country?: string;
+}>;
+
+/**
+ * Predefined Facebook App Event names.
+ */
+export const AppEvents = {
+  AchievedLevel: "fb_mobile_level_achieved",
+  AdClick: "AdClick",
+  AdImpression: "AdImpression",
+  AddedPaymentInfo: "fb_mobile_add_payment_info",
+  AddedToCart: "fb_mobile_add_to_cart",
+  AddedToWishlist: "fb_mobile_add_to_wishlist",
+  CompletedRegistration: "fb_mobile_complete_registration",
+  CompletedTutorial: "fb_mobile_tutorial_completion",
+  Contact: "Contact",
+  CustomizeProduct: "CustomizeProduct",
+  Donate: "Donate",
+  FindLocation: "FindLocation",
+  InitiatedCheckout: "fb_mobile_initiated_checkout",
+  Purchased: "fb_mobile_purchase",
+  Rated: "fb_mobile_rate",
+  Searched: "fb_mobile_search",
+  SpentCredits: "fb_mobile_spent_credits",
+  Schedule: "Schedule",
+  StartTrial: "StartTrial",
+  SubmitApplication: "SubmitApplication",
+  Subscribe: "Subscribe",
+  UnlockedAchievement: "fb_mobile_achievement_unlocked",
+  ViewedContent: "fb_mobile_content_view",
+} as const;
+
+/**
+ * Predefined Facebook App Event parameter names.
+ */
+export const AppEventParams = {
+  AddType: "fb_mobile_add_type",
+  Content: "fb_content",
+  ContentID: "fb_content_id",
+  ContentType: "fb_content_type",
+  Currency: "fb_currency",
+  Description: "fb_description",
+  Level: "fb_level",
+  NumItems: "fb_num_items",
+  MaxRatingValue: "fb_max_rating_value",
+  OrderId: "fb_order_id",
+  PaymentInfoAvailable: "fb_payment_info_available",
+  RegistrationMethod: "fb_registration_method",
+  SearchString: "fb_search_string",
+  Success: "fb_success",
+  ValueNo: "0",
+  ValueYes: "1",
+} as const;