customerio-expo-plugin 3.1.0 → 3.3.0

package/plugin/src/helpers/native-files/ios/CustomerIOSDKInitializer.swift

@@ -1,6 +1,7 @@
 import CioDataPipelines
 import CioInternalCommon
 import CioMessagingInApp
+{{LOCATION_MODULE_IMPORT}}
 
 class CustomerIOSDKInitializer {
     static func initialize() {
@@ -23,6 +24,7 @@ class CustomerIOSDKInitializer {
         setIfDefined(value: {{SCREEN_VIEW_USE}}, thenPassItTo: builder.screenViewUse) { ScreenView.getScreenView($0) }
         setIfDefined(value: {{MIGRATION_SITE_ID}}, thenPassItTo: builder.migrationSiteId)
 
+        {{LOCATION_MODULE_INIT}}
         CustomerIO.initialize(withConfig: builder.build())
 
         if let siteId = siteId {

package/plugin/src/helpers/native-files/ios/apn/CioSdkAppDelegateHandler.swift

@@ -42,7 +42,7 @@ public class CioSdkAppDelegateHandler: NSObject {
     MessagingPushAPN.initialize(
       withConfig: MessagingPushConfigBuilder()
         .autoFetchDeviceToken({{AUTO_FETCH_DEVICE_TOKEN}})
-        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
+{{APP_GROUP_ID_BUILDER_LINE}}        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
         .autoTrackPushEvents({{AUTO_TRACK_PUSH_EVENTS}})
         .build()
     )

package/plugin/src/helpers/native-files/ios/apn/NotificationService.swift

@@ -12,7 +12,7 @@ public class NotificationServiceCioManager : NSObject {
     MessagingPushAPN.initializeForExtension(
       withConfig: MessagingPushConfigBuilder(cdpApiKey: Env.customerIOCdpApiKey)
         .region(Env.customerIORegion)
-        .build()
+{{APP_GROUP_ID_BUILDER_LINE}}        .build()
     )
     
     MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)

package/plugin/src/helpers/native-files/ios/apn/PushService.swift

@@ -15,7 +15,7 @@ public class CIOAppPushNotificationsHandler : NSObject {
     MessagingPushAPN.initialize(
       withConfig: MessagingPushConfigBuilder()
         .autoFetchDeviceToken({{AUTO_FETCH_DEVICE_TOKEN}})
-        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
+{{APP_GROUP_ID_BUILDER_LINE}}        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
         .autoTrackPushEvents({{AUTO_TRACK_PUSH_EVENTS}})
         .build()
     )

package/plugin/src/helpers/native-files/ios/fcm/CioSdkAppDelegateHandler.swift

@@ -52,7 +52,7 @@ public class CioSdkAppDelegateHandler: NSObject {
     MessagingPushFCM.initialize(
       withConfig: MessagingPushConfigBuilder()
         .autoFetchDeviceToken({{AUTO_FETCH_DEVICE_TOKEN}})
-        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
+{{APP_GROUP_ID_BUILDER_LINE}}        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
         .autoTrackPushEvents({{AUTO_TRACK_PUSH_EVENTS}})
         .build()
     )

package/plugin/src/helpers/native-files/ios/fcm/NotificationService.swift

@@ -12,7 +12,7 @@ public class NotificationServiceCioManager : NSObject {
     MessagingPushFCM.initializeForExtension(
       withConfig: MessagingPushConfigBuilder(cdpApiKey: Env.customerIOCdpApiKey)
         .region(Env.customerIORegion)
-        .build()
+{{APP_GROUP_ID_BUILDER_LINE}}        .build()
     )
     
     MessagingPush.shared.didReceive(request, withContentHandler: contentHandler)

package/plugin/src/helpers/native-files/ios/fcm/PushService.swift

@@ -23,7 +23,7 @@ public class CIOAppPushNotificationsHandler : NSObject {
     MessagingPushFCM.initialize(
       withConfig: MessagingPushConfigBuilder()
         .autoFetchDeviceToken({{AUTO_FETCH_DEVICE_TOKEN}})
-        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
+{{APP_GROUP_ID_BUILDER_LINE}}        .showPushAppInForeground({{SHOW_PUSH_APP_IN_FOREGROUND}})
         .autoTrackPushEvents({{AUTO_TRACK_PUSH_EVENTS}})
         .build()
     )

package/plugin/src/helpers/utils/injectCIOPodfileCode.ts

@@ -4,9 +4,40 @@ import { getRelativePathToRNSDK } from '../constants/ios';
 import { injectCodeByRegex } from './codeInjection';
 import { FileManagement } from './fileManagement';
 
+export type InjectCIOPodfileOptions = {
+  /** When true, add the location subspec. When false/omit, use single push subspec only. */
+  locationEnabled?: boolean;
+  /** When false and locationEnabled, inject only :subspecs => ['location']. When true, use push + location. */
+  hasPush?: boolean;
+};
+
+/** Builds the host app pod line for the Podfile (single subspec or :subspecs with location). Exported for tests. */
+export function buildHostAppPodSnippet(
+  iosPath: string,
+  isFcmPushProvider: boolean,
+  options?: InjectCIOPodfileOptions
+): string {
+  const path = getRelativePathToRNSDK(iosPath);
+  const locationEnabled = options?.locationEnabled === true;
+  const hasPush = options?.hasPush !== false;
+
+  if (!locationEnabled) {
+    const subspec = isFcmPushProvider ? 'fcm' : 'apn';
+    return `pod 'customerio-reactnative/${subspec}', :path => '${path}'`;
+  }
+
+  if (!hasPush) {
+    return `pod 'customerio-reactnative', :subspecs => ['location'], :path => '${path}'`;
+  }
+
+  const pushSubspec = isFcmPushProvider ? 'fcm' : 'apn';
+  return `pod 'customerio-reactnative', :subspecs => ['${pushSubspec}', 'location'], :path => '${path}'`;
+}
+
 export async function injectCIOPodfileCode(
   iosPath: string,
-  isFcmPushProvider: boolean
+  isFcmPushProvider: boolean,
+  options?: InjectCIOPodfileOptions
 ) {
   const blockStart = '# --- CustomerIO Host App START ---';
   const blockEnd = '# --- CustomerIO Host App END ---';
@@ -21,10 +52,11 @@ export async function injectCIOPodfileCode(
     // Find that line in the Podfile and then we will insert our code above that line.
     const lineInPodfileToInjectSnippetBefore = /post_install do \|installer\|/;
 
+    const podLine = buildHostAppPodSnippet(iosPath, isFcmPushProvider, options);
+
     const snippetToInjectInPodfile = `
 ${blockStart}
-  pod 'customerio-reactnative/${isFcmPushProvider ? 'fcm' : 'apn'
-      }', :path => '${getRelativePathToRNSDK(iosPath)}'
+  ${podLine}
 ${blockEnd}
 `.trim();
 

package/plugin/src/helpers/utils/patchLocationCode.ts

@@ -0,0 +1,80 @@
+import type { LocationTrackingMode } from '../../types/cio-types';
+import { PLATFORM, type Platform } from '../constants/common';
+
+const VALID_TRACKING_MODES: LocationTrackingMode[] = ['OFF', 'MANUAL', 'ON_APP_START'];
+
+/** Options for location module in generated native initializer */
+export type LocationInitOptions = {
+  enabled: boolean;
+  trackingMode?: LocationTrackingMode;
+};
+
+function normalizeTrackingMode(
+  rawMode: string | undefined
+): LocationTrackingMode {
+  const upper = rawMode?.toUpperCase();
+  return upper && VALID_TRACKING_MODES.includes(upper as LocationTrackingMode)
+    ? (upper as LocationTrackingMode)
+    : 'MANUAL';
+}
+
+/**
+ * Replaces {{LOCATION_MODULE_IMPORT}} and {{LOCATION_MODULE_INIT}} placeholders
+ * in SDK initializer template content for the given platform.
+ */
+export function patchLocationPlaceholders(
+  content: string,
+  platform: Platform,
+  locationOptions?: LocationInitOptions
+): string {
+  const locationEnabled = locationOptions?.enabled === true;
+  const trackingMode = normalizeTrackingMode(locationOptions?.trackingMode);
+
+  if (platform === PLATFORM.ANDROID) {
+    if (locationEnabled) {
+      return content
+        .replace(
+          /\{\{LOCATION_MODULE_IMPORT\}\}/g,
+          `import io.customer.location.LocationModuleConfig
+import io.customer.location.LocationTrackingMode
+import io.customer.location.ModuleLocation
+`
+        )
+        .replace(
+          /\{\{LOCATION_MODULE_INIT\}\}/g,
+          `if (io.customer.reactnative.sdk.BuildConfig.CIO_LOCATION_ENABLED) {
+            addCustomerIOModule(
+                ModuleLocation(
+                    LocationModuleConfig.Builder()
+                        .setLocationTrackingMode(LocationTrackingMode.${trackingMode})
+                        .build()
+                )
+            )
+        }
+        `
+        );
+    }
+    return content
+      .replace(/\n\{\{LOCATION_MODULE_IMPORT\}\}\n/g, '\n')
+      .replace(/\n\s*\{\{LOCATION_MODULE_INIT\}\}\n/g, '\n');
+  }
+
+  // iOS
+  if (locationEnabled) {
+    const modeSwift =
+      trackingMode === 'OFF'
+        ? '.off'
+        : trackingMode === 'ON_APP_START'
+          ? '.onAppStart'
+          : '.manual';
+    return content
+      .replace(/\{\{LOCATION_MODULE_IMPORT\}\}/g, 'import CioLocation\n')
+      .replace(
+        /\{\{LOCATION_MODULE_INIT\}\}/g,
+        `_ = builder.addModule(LocationModule(config: LocationConfig(mode: ${modeSwift})))`
+      );
+  }
+  return content
+    .replace(/\n\{\{LOCATION_MODULE_IMPORT\}\}\n/g, '\n')
+    .replace(/\n\s*\{\{LOCATION_MODULE_INIT\}\}\n/g, '\n\n');
+}

package/plugin/src/helpers/utils/patchPluginNativeCode.ts

@@ -2,6 +2,12 @@ import type { NativeSDKConfig } from '../../types/cio-types';
 import { getPluginVersion } from '../../utils/plugin';
 import { validateNativeSDKConfig } from '../../utils/validation';
 import { PLATFORM, type Platform } from '../constants/common';
+import {
+  type LocationInitOptions,
+  patchLocationPlaceholders,
+} from './patchLocationCode';
+
+export type { LocationInitOptions };
 
 /**
  * Shared utility function to perform common SDK config replacements
@@ -10,7 +16,8 @@ import { PLATFORM, type Platform } from '../constants/common';
 export function patchNativeSDKInitializer(
   rawContent: string,
   platform: Platform,
-  sdkConfig: NativeSDKConfig
+  sdkConfig: NativeSDKConfig,
+  locationOptions?: LocationInitOptions
 ): string {
   // Validate SDK configuration to ensure all fields are present and 
   // correct at the time of patching in prebuild
@@ -98,5 +105,7 @@ export function patchNativeSDKInitializer(
     (configValue) => `"${configValue}"`
   );
 
+  content = patchLocationPlaceholders(content, platform, locationOptions);
+
   return content;
 }

package/plugin/src/index.ts

@@ -3,7 +3,13 @@ import type { ExpoConfig } from '@expo/config-types';
 import { withCIOAndroid } from './android/withCIOAndroid';
 import { isExpoVersion53OrHigher } from './ios/utils';
 import { withCIOIos } from './ios/withCIOIos';
-import type { CustomerIOPluginOptions } from './types/cio-types';
+import type {
+  CustomerIOPluginOptions,
+  LocationTrackingMode,
+  NativeSDKConfig,
+} from './types/cio-types';
+
+export type { LocationTrackingMode, NativeSDKConfig };
 
 // Entry point for config plugin
 function withCustomerIOPlugin(
@@ -20,8 +26,8 @@ function withCustomerIOPlugin(
   }
 
   // Apply platform specific modifications
-  config = withCIOIos(config, props.config, props.ios);
-  config = withCIOAndroid(config, props.config, props.android);
+  config = withCIOIos(config, props.config, props.ios, props.location);
+  config = withCIOAndroid(config, props.config, props.android, props.location);
 
   return config;
 }

package/plugin/src/ios/withCIOIos.ts

@@ -1,11 +1,14 @@
 import type { ExpoConfig } from '@expo/config-types';
+import { withEntitlementsPlist } from '@expo/config-plugins';
 import type {
   CustomerIOPluginOptionsIOS,
   CustomerIOPluginPushNotificationOptions,
+  CustomerIOPluginLocationOptions,
   NativeSDKConfig,
 } from '../types/cio-types';
 import { mergeConfigWithEnvValues } from '../utils/config';
 import { logger } from '../utils/logger';
+import { validatePushNotificationOptions } from '../utils/validation';
 import { isExpoVersion53OrHigher } from './utils';
 import { withAppDelegateModifications } from './withAppDelegateModifications';
 import { withCIOIosSwift } from './withCIOIosSwift';
@@ -17,13 +20,16 @@ export function withCIOIos(
   config: ExpoConfig,
   sdkConfig?: NativeSDKConfig,
   props?: CustomerIOPluginOptionsIOS,
+  location?: CustomerIOPluginLocationOptions,
 ) {
   const isSwiftProject = isExpoVersion53OrHigher(config);
   const platformConfig = mergeDeprecatedPropertiesAndLogWarnings(props);
+  const locationEnabled = location?.enabled === true;
 
   if (platformConfig?.pushNotification) {
+    validatePushNotificationOptions(platformConfig.pushNotification);
     if (isSwiftProject) {
-      config = withCIOIosSwift(config, sdkConfig, platformConfig);
+      config = withCIOIosSwift(config, sdkConfig, platformConfig, location);
     } else {
       // Auto initialization is only supported in Swift projects (Expo SDK 53+)
       // Legacy Objective-C projects only support push notifications
@@ -33,10 +39,41 @@ export function withCIOIos(
     platformConfig.pushNotification.env = platformConfig.pushNotification.env
       || mergeConfigWithEnvValues(platformConfig, sdkConfig);
     config = withCioNotificationsXcodeProject(config, platformConfig);
-    config = withCioXcodeProject(config, platformConfig);
+    config = withCioXcodeProject(config, {
+      ...platformConfig,
+      podfileOptions: {
+        locationEnabled,
+        hasPush: true,
+      },
+    });
     config = withGoogleServicesJsonFile(config, platformConfig);
+
+    // Merge App Group entitlements on host only when appGroupId is explicitly set
+    const appGroupId = platformConfig.pushNotification?.appGroupId;
+    if (appGroupId) {
+      config = withEntitlementsPlist(config, (entitlementsConfig) => {
+        const entitlements = entitlementsConfig.modResults as Record<string, unknown>;
+        const existing = (entitlements['com.apple.security.application-groups'] as string[] | undefined) ?? [];
+        if (!existing.includes(appGroupId)) {
+          entitlements['com.apple.security.application-groups'] = [...existing, appGroupId];
+        }
+        return entitlementsConfig;
+      });
+    }
   } else if (sdkConfig && isSwiftProject) {
-    config = withCIOIosSwift(config, sdkConfig, platformConfig);
+    config = withCIOIosSwift(config, sdkConfig, platformConfig, location);
+    if (locationEnabled) {
+      config = withCioXcodeProject(config, {
+        ...platformConfig,
+        podfileOptions: { locationEnabled: true, hasPush: false },
+      });
+    }
+  } else if (locationEnabled) {
+    // Location-only: no push, no config. Still add Podfile location subspec so CIO_LOCATION_ENABLED is set and native location code is included.
+    config = withCioXcodeProject(config, {
+      ...platformConfig,
+      podfileOptions: { locationEnabled: true, hasPush: false },
+    });
   }
 
   return config;

package/plugin/src/ios/withCIOIosSwift.ts

@@ -17,7 +17,11 @@ import {
 import { replaceCodeByRegex } from '../helpers/utils/codeInjection';
 import { FileManagement } from '../helpers/utils/fileManagement';
 import { patchNativeSDKInitializer } from '../helpers/utils/patchPluginNativeCode';
-import type { CustomerIOPluginOptionsIOS, NativeSDKConfig } from '../types/cio-types';
+import type {
+  CustomerIOPluginOptionsIOS,
+  CustomerIOPluginLocationOptions,
+  NativeSDKConfig,
+} from '../types/cio-types';
 import { logger } from '../utils/logger';
 import { getIosNativeFilesPath } from '../utils/plugin';
 import { copyFileToXcode, getOrCreateCustomerIOGroup } from '../utils/xcode';
@@ -34,6 +38,7 @@ const copyAndConfigureAppDelegateHandler = (
   config: ExportedConfigWithProps<XcodeProject>,
   sdkConfig?: NativeSDKConfig,
   props?: CustomerIOPluginOptionsIOS,
+  location?: CustomerIOPluginLocationOptions,
 ): ExportedConfigWithProps<XcodeProject> => {
   // Destination path in the iOS project
   const projectName = config.modRequest.projectName || '';
@@ -59,6 +64,7 @@ const copyAndConfigureAppDelegateHandler = (
       projectName,
       sdkConfig,
       props,
+      location,
     });
   } else if (sdkConfig) {
     // Copy only CustomerIOSDKInitializer.swift for auto-init without push notifications
@@ -68,6 +74,7 @@ const copyAndConfigureAppDelegateHandler = (
       iosProjectRoot,
       projectName,
       sdkConfig,
+      location,
     });
   }
 
@@ -81,6 +88,7 @@ const copyAndConfigurePushAppDelegateHandler = ({
   projectName,
   sdkConfig,
   props,
+  location,
 }: {
   xcodeProject: XcodeProject;
   group: XcodeProject['pbxCreateGroup'];
@@ -88,6 +96,7 @@ const copyAndConfigurePushAppDelegateHandler = ({
   projectName: string;
   sdkConfig: NativeSDKConfig | undefined;
   props: CustomerIOPluginOptionsIOS;
+  location?: CustomerIOPluginLocationOptions;
 }) => {
   const useFcm = isFcmPushProvider(props);
 
@@ -153,10 +162,20 @@ const copyAndConfigurePushAppDelegateHandler = ({
     showPushAppInForeground.toString()
   );
 
+  const appGroupId = props.pushNotification?.appGroupId;
+  const appGroupIdBuilderLine = appGroupId
+    ? `        .appGroupId(${JSON.stringify(appGroupId)})\n`
+    : '';
+  handlerFileContent = replaceCodeByRegex(
+    handlerFileContent,
+    /\{\{APP_GROUP_ID_BUILDER_LINE\}\}/,
+    appGroupIdBuilderLine
+  );
+
   // Add auto initialization if sdkConfig is provided
   if (sdkConfig) {
     // Also copy CustomerIOSDKInitializer.swift for auto-initialization
-    copyAndConfigureNativeSDKInitializer({ xcodeProject, group, iosProjectRoot, projectName, sdkConfig });
+    copyAndConfigureNativeSDKInitializer({ xcodeProject, group, iosProjectRoot, projectName, sdkConfig, location });
 
     // Inject auto initialization call before MessagingPush initialization
     handlerFileContent = handlerFileContent.replace(CIO_MESSAGING_PUSH_APP_DELEGATE_INIT_REGEX, CIO_NATIVE_SDK_INITIALIZE_SNIPPET + '$1');
@@ -171,13 +190,18 @@ const copyAndConfigureNativeSDKInitializer = ({
   iosProjectRoot,
   projectName,
   sdkConfig,
+  location,
 }: {
   xcodeProject: XcodeProject;
   group: XcodeProject['pbxCreateGroup'];
   iosProjectRoot: string;
   projectName: string;
   sdkConfig: NativeSDKConfig;
+  location?: CustomerIOPluginLocationOptions;
 }) => {
+  const locationOptions = location
+    ? { enabled: location.enabled === true, trackingMode: sdkConfig?.location?.trackingMode }
+    : undefined;
   const filename = 'CustomerIOSDKInitializer.swift';
   const sourcePath = path.join(getIosNativeFilesPath(), filename);
   // Add the CustomerIOSDKInitializer.swift file to the same Xcode group as CioSdkAppDelegateHandler
@@ -187,7 +211,8 @@ const copyAndConfigureNativeSDKInitializer = ({
     projectName,
     sourceFilePath: sourcePath,
     targetFileName: filename,
-    transform: (content) => patchNativeSDKInitializer(content, PLATFORM.IOS, sdkConfig),
+    transform: (content) =>
+      patchNativeSDKInitializer(content, PLATFORM.IOS, sdkConfig, locationOptions),
     customerIOGroup: group,
   });
 };
@@ -196,10 +221,11 @@ export const withCIOIosSwift = (
   configOuter: ExpoConfig,
   sdkConfig?: NativeSDKConfig,
   props?: CustomerIOPluginOptionsIOS,
+  location?: CustomerIOPluginLocationOptions,
 ) => {
   // First, copy required swift files to iOS folder and add it to Xcode project
   configOuter = withXcodeProject(configOuter, async (config) => {
-    return copyAndConfigureAppDelegateHandler(config, sdkConfig, props);
+    return copyAndConfigureAppDelegateHandler(config, sdkConfig, props, location);
   });
 
   // Modify the AppDelegate based on configuration

package/plugin/src/ios/withNotificationsXcodeProject.ts

@@ -135,6 +135,25 @@ const addRichPushXcodeProj = async (
 
   const platformSpecificFiles = ['NotificationService.swift'];
 
+  const nseEntitlementsFilename = 'NotificationService.entitlements';
+  const appGroupId = options.pushNotification?.appGroupId;
+
+  // Write NSE entitlements file only when appGroupId is explicitly configured
+  if (appGroupId) {
+    const nseEntitlementsContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.application-groups</key>
+  <array>
+    <string>${appGroupId}</string>
+  </array>
+</dict>
+</plist>
+`;
+    FileManagement.writeFile(`${nsePath}/${nseEntitlementsFilename}`, nseEntitlementsContent);
+  }
+
   const commonFiles = [
     PLIST_FILENAME,
     'NotificationService.h',
@@ -170,10 +189,19 @@ const addRichPushXcodeProj = async (
     infoPlistTargetFile,
   });
   updateNseEnv(getTargetFile(ENV_FILENAME), options.pushNotification?.env);
+  updateNseNotificationService(getTargetFile('NotificationService.swift'), options.pushNotification?.appGroupId);
+
+  // The entitlements file is generated (not copied from source), so it's listed separately
+  // for the Xcode group so it appears in the file navigator
+  const allGroupFiles = [
+    ...platformSpecificFiles,
+    ...commonFiles,
+    ...(appGroupId ? [nseEntitlementsFilename] : []),
+  ];
 
   // Create new PBXGroup for the extension
   const extGroup = xcodeProject.addPbxGroup(
-    [...platformSpecificFiles, ...commonFiles], // Combine platform-specific and common files,
+    allGroupFiles,
     CIO_NOTIFICATION_TARGET_NAME,
     CIO_NOTIFICATION_TARGET_NAME
   );
@@ -247,6 +275,9 @@ const addRichPushXcodeProj = async (
       buildSettingsObj.TARGETED_DEVICE_FAMILY = TARGETED_DEVICE_FAMILY;
       buildSettingsObj.CODE_SIGN_STYLE = 'Automatic';
       buildSettingsObj.SWIFT_VERSION = 4.2;
+      if (appGroupId) {
+        buildSettingsObj.CODE_SIGN_ENTITLEMENTS = `${CIO_NOTIFICATION_TARGET_NAME}/${nseEntitlementsFilename}`;
+      }
     }
   }
 
@@ -284,6 +315,20 @@ const updateNseInfoPlist = (payload: {
   FileManagement.writeFile(payload.infoPlistTargetFile, plistFileString);
 };
 
+const updateNseNotificationService = (
+  notificationServiceFile: string,
+  appGroupId?: string,
+) => {
+  const APP_GROUP_ID_BUILDER_LINE_RE = /\{\{APP_GROUP_ID_BUILDER_LINE\}\}/;
+
+  let content = FileManagement.readFile(notificationServiceFile);
+  const builderLine = appGroupId
+    ? `        .appGroupId(${JSON.stringify(appGroupId)})\n`
+    : '';
+  content = replaceCodeByRegex(content, APP_GROUP_ID_BUILDER_LINE_RE, builderLine);
+  FileManagement.writeFile(notificationServiceFile, content);
+};
+
 const updateNseEnv = (
   envFileName: string,
   richPushConfig?: RichPushConfig
@@ -429,5 +474,15 @@ const updatePushFile = (
     showPushAppInForeground.toString()
   );
 
+  const appGroupId = options.pushNotification?.appGroupId;
+  const appGroupIdBuilderLine = appGroupId
+    ? `        .appGroupId(${JSON.stringify(appGroupId)})\n`
+    : '';
+  envFileContent = replaceCodeByRegex(
+    envFileContent,
+    /\{\{APP_GROUP_ID_BUILDER_LINE\}\}/,
+    appGroupIdBuilderLine
+  );
+
   FileManagement.writeFile(envFileName, envFileContent);
 };

package/plugin/src/ios/withXcodeProject.ts

@@ -1,18 +1,35 @@
 import type { ConfigPlugin } from '@expo/config-plugins';
 import { withXcodeProject } from '@expo/config-plugins';
 
-import { injectCIOPodfileCode } from '../helpers/utils/injectCIOPodfileCode';
+import {
+  injectCIOPodfileCode,
+  type InjectCIOPodfileOptions,
+} from '../helpers/utils/injectCIOPodfileCode';
 import type { CustomerIOPluginOptionsIOS } from '../types/cio-types';
 import { isFcmPushProvider } from './utils';
 
-export const withCioXcodeProject: ConfigPlugin<CustomerIOPluginOptionsIOS> = (
+export type WithCioXcodeProjectOptions = {
+  /** Options for Podfile host app snippet (location subspec, etc.) */
+  podfileOptions?: InjectCIOPodfileOptions;
+};
+
+/** Props for the CIO Xcode project mod; push options are optional when only location is enabled. */
+export type WithCioXcodeProjectProps = Partial<CustomerIOPluginOptionsIOS> &
+  WithCioXcodeProjectOptions;
+
+export const withCioXcodeProject: ConfigPlugin<WithCioXcodeProjectProps> = (
   config,
   cioProps
 ) => {
   return withXcodeProject(config, async (props) => {
     const iosPath = props.modRequest.platformProjectRoot;
+    const podfileOptions = cioProps?.podfileOptions;
 
-    await injectCIOPodfileCode(iosPath, isFcmPushProvider(cioProps));
+    await injectCIOPodfileCode(
+      iosPath,
+      isFcmPushProvider(cioProps as CustomerIOPluginOptionsIOS | undefined),
+      podfileOptions
+    );
 
     return props;
   });

package/plugin/src/types/cio-types.ts

@@ -88,6 +88,13 @@ export type CustomerIOPluginOptionsAndroid = {
   disableAndroid16Support?: boolean;
 };
 
+/**
+ * Location tracking mode for the Customer.io SDK location module.
+ * Location is off by default. Only used when location is enabled (plugin option location.enabled: true).
+ * @public
+ */
+export type LocationTrackingMode = 'OFF' | 'MANUAL' | 'ON_APP_START';
+
 /**
  * SDK configuration options for auto initialization
  * @public
@@ -101,6 +108,24 @@ export type NativeSDKConfig = {
   logLevel?: 'none' | 'error' | 'info' | 'debug'; // Default: 'debug'. Controls SDK logging verbosity
   siteId?: string; // Optional, if only siteId defined, migrationSiteId = siteId
   migrationSiteId?: string; // Optional, if only migrationSiteId defined, siteId should be null
+  /**
+   * Location module config. Location is off by default; only applied when plugin option location.enabled is true.
+   * trackingMode: 'MANUAL' (host app controls when location is captured, default),
+   * 'ON_APP_START' (SDK captures once per launch when app becomes active), or 'OFF'.
+   */
+  location?: {
+    trackingMode?: LocationTrackingMode;
+  };
+};
+
+/**
+ * Location is off by default. When true, enables the Customer.io SDK location native module (iOS Podfile location subspec,
+ * Android gradle.properties flag). Permissions and privacy keys (Info.plist, AndroidManifest)
+ * remain the host app's responsibility.
+ * @public
+ */
+export type CustomerIOPluginLocationOptions = {
+  enabled?: boolean;
 };
 
 /**
@@ -111,6 +136,11 @@ export type CustomerIOPluginOptions = {
   config?: NativeSDKConfig; // If defined, enables auto initialization of native SDK
   android: CustomerIOPluginOptionsAndroid;
   ios: CustomerIOPluginOptionsIOS;
+  /**
+   * Location is off by default. When location.enabled is true, the plugin adds SDK build-time setup (Podfile location subspec,
+   * gradle.properties). Host apps must add their own location permissions and privacy usage strings.
+   */
+  location?: CustomerIOPluginLocationOptions;
 };
 
 /**
@@ -141,4 +171,12 @@ export type CustomerIOPluginPushNotificationOptions = {
    * Optional if `config` is provided at the top level.
    */
   env?: RichPushConfig;
+
+  /**
+   * iOS App Group identifier shared between the host app and the Notification Service Extension.
+   * When set, `.appGroupId(...)` is injected into the MessagingPushConfigBuilder, the identifier
+   * is added to the host app entitlements, and an NSE entitlements file is written.
+   * When omitted, the native SDK handles group discovery on its own and no entitlements are added.
+   */
+  appGroupId?: string;
 };