cordova-plugin-reteno 2.2.0 → 2.2.1

package/docs/Ionic/Tracking user behaviour/README.md

@@ -0,0 +1,31 @@
+# Tracking user behaviour
+
+## Track custom events
+
+```ts
+await this.reteno.logEvent({
+  eventName: 'EVENT_NAME',
+  date: new Date().toISOString(),
+  parameters: [{ name: 'Additional parameter', value: 'Additional value' }],
+});
+```
+
+## Force push cached data
+
+```ts
+await this.reteno.forcePushData();
+```
+
+On iOS this uses a technical `logEvent(..., forcePush: true)` call under the hood.
+
+## Log screen view events
+
+```ts
+await this.reteno.logScreenView('HomeScreen');
+```
+
+## Lifecycle tracking options
+
+See configuration and examples in:
+
+- [AppLifeCycleEvents/README.md](../AppLifeCycleEvents/README.md)

package/docs/Ionic/Tracking user information/README.md

@@ -0,0 +1,98 @@
+# Tracking user information
+
+Use `AwesomeCordovaPluginReteno` service methods.
+
+## Set user attributes (identified user)
+
+```ts
+await this.reteno.setUserAttributes({
+  externalUserId: 'USER_ID',
+  user: {
+    userAttributes: {
+      email: 'john.doe@example.com',
+      phone: '+1234567890',
+      firstName: 'John',
+      lastName: 'Doe',
+      languageCode: 'en',
+      timeZone: 'Europe/Kyiv',
+      marketId: 'market_1',
+      address: {
+        region: 'Kyivska',
+        town: 'Kyiv',
+        address: 'Khreshchatyk St, 1',
+        postcode: '01001',
+      },
+      fields: [{ key: 'plan', value: 'premium' }],
+    },
+    subscriptionKeys: ['news', 'promotions'],
+    groupNamesInclude: ['beta-testers'],
+    groupNamesExclude: ['unsubscribed'],
+  },
+});
+```
+
+## Set anonymous user attributes
+
+```ts
+await this.reteno.setAnonymousUserAttributes({
+  firstName: 'John',
+  lastName: 'Doe',
+  languageCode: 'en',
+  timeZone: 'Europe/Kyiv',
+  marketId: 'market_1',
+  address: {
+    region: 'Kyivska',
+    town: 'Kyiv',
+    address: 'Khreshchatyk St, 1',
+    postcode: '01001',
+  },
+  fields: [{ key: 'utm_source', value: 'google' }],
+});
+```
+
+Anonymous attributes cannot include `phone` or `email`.
+
+## Multi-account mode
+
+```ts
+await this.reteno.setMultiAccountUserAttributes({
+  externalUserId: 'user-123',
+  user: {
+    userAttributes: {
+      email: 'john.doe@example.com',
+      firstName: 'John',
+      lastName: 'Doe',
+      marketId: 'market_1',
+    },
+  },
+});
+```
+
+## Market ID
+
+`marketId` requires `cordova-plugin-reteno@2.1.0`. The
+`awesome-cordova-plugins-reteno@9.2.0` wrapper includes its TypeScript declaration. It is
+supported by `setUserAttributes`, `setAnonymousUserAttributes`, and
+`setMultiAccountUserAttributes`.
+
+- The value can contain up to 64 Latin letters, digits, hyphens (`-`), and underscores (`_`).
+- Pass an empty string to clear the existing value:
+
+```ts
+await this.reteno.setUserAttributes({
+  externalUserId: 'USER_ID',
+  user: {
+    userAttributes: {
+      marketId: '',
+    },
+  },
+});
+```
+
+- Omit `marketId` to keep the existing value unchanged.
+- The feature requires Reteno Android SDK 2.9.5+ or Reteno iOS SDK 2.7.1+. These versions are included in `cordova-plugin-reteno@2.1.0`.
+
+## Notes
+
+- `languageCode`: RFC 5646 (example: `de-AT`)
+- `timeZone`: TZ database value (example: `Europe/Kyiv`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-reteno",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "The Reteno Cordova Plugin for Mobile Customer Engagement and Analytics solutions",
   "types": "./types/index.ts",
   "files": [

package/plugin.xml

@@ -1,16 +1,20 @@
 <?xml version='1.0' encoding='utf-8'?>
-<plugin id="cordova-plugin-reteno" version="2.2.0" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
+<plugin id="cordova-plugin-reteno" version="2.2.1" xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
     <name>cordova-plugin-reteno</name>
     <engines>
         <engine name="cordova-android" version=">=12.0.0" />
         <engine name="cordova-ios" version=">=8.0.0" />
     </engines>
+    <preference name="RETENO_ACCESS_KEY" default="MISSING" />
+    <!-- Deprecated compatibility alias. Use RETENO_ACCESS_KEY for new integrations. -->
     <preference name="SDK_ACCESS_KEY" default="MISSING" />
     <preference name="IOS_DEVICE_TOKEN_HANDLING_MODE" default="manual" />
     <hook type="before_plugin_install" src="scripts/validate-install.js" />
     <hook type="after_plugin_install" src="scripts/android-fcm-setup.js" />
     <hook type="after_platform_add" src="scripts/android-fcm-setup.js" />
     <hook type="after_prepare" src="scripts/android-fcm-setup.js" />
+    <hook type="before_plugin_install" src="scripts/ios-podfile-use-modular-headers.js" />
+    <hook type="before_prepare" src="scripts/ios-podfile-use-modular-headers.js" />
     <js-module name="cordova-plugin-reteno" src="www/cordova-plugin-reteno.js">
         <clobbers target="RetenoPlugin" />
     </js-module>
@@ -21,6 +25,8 @@
     </config-file>
 
     <config-file target="AndroidManifest.xml" parent="/manifest/application">
+        <meta-data android:name="com.reteno.RETENO_ACCESS_KEY" android:value="$RETENO_ACCESS_KEY" />
+        <!-- Deprecated compatibility alias. -->
         <meta-data android:name="com.reteno.SDK_ACCESS_KEY" android:value="$SDK_ACCESS_KEY" />
         <provider
             android:name="com.reteno.plugin.RetenoNotificationGroupingRuleProvider"
@@ -67,12 +73,24 @@
   </config-file>
 
   <podspec>
+    <!--
+      Empty <config/> is required even without <source> entries: cordova-ios's
+      Api.js#removePodSpecs does `Object.keys(obj.sources)` unconditionally (unlike
+      addPodSpecs, which guards it) and crashes with "Cannot convert undefined or
+      null to object" on `cordova plugin rm` when <config> is absent, since
+      PluginInfo#getPodSpecs() then returns `sources: undefined` instead of `{}`.
+      That crash aborts the uninstall before it finishes, which then leaves iOS
+      plugin bookkeeping (plugins/ios.json) stale so a later reinstall thinks the
+      plugin is "already installed" and skips re-copying its www/ bridge file.
+    -->
+    <config></config>
     <pods>
-      <pod name="Reteno" spec="2.7.3" />
+      <pod name="Reteno" spec="2.7.4" />
       <pod name="FirebaseMessaging" />
     </pods>
   </podspec>
 
   <source-file src="src/ios/RetenoPlugin.swift" />
+  <source-file src="src/ios/RetenoPluginBootstrap.m" />
 </platform>
 </plugin>

package/scripts/ios-podfile-use-modular-headers.js

@@ -0,0 +1,109 @@
+/*
+ * Cordova hook: add `use_modular_headers!` to platforms/ios/Podfile.
+ *
+ * cordova-ios auto-generates the Podfile and does not expose a config.xml/plugin.xml
+ * knob for arbitrary CocoaPods directives other than `use_frameworks!` and
+ * `inhibit_all_warnings!` (see cordova-ios/lib/Podfile.js declarationRegexpMap).
+ * Cordova links pods statically by default (no `use_frameworks!`), and recent
+ * Firebase pods (pulled in via `pod 'FirebaseMessaging'`) depend on GoogleUtilities,
+ * which does not define modules -- `pod install` refuses to proceed under static
+ * linking unless `use_modular_headers!` is set.
+ *
+ * The generated Podfile is fully rewritten on every `prepare`, but cordova-ios seeds
+ * its in-memory declarations by parsing whatever already sits between the
+ * `platform :ios, 'x.y'` and `target 'App' do` lines (any non-comment line there is
+ * treated as a raw declaration and re-emitted verbatim). So patching the file before
+ * cordova-ios's own prepare runs (before_prepare, ahead of `preparePlatforms`) is
+ * enough for our line to survive the regeneration.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DECLARATION = 'use_modular_headers!';
+
+function exists(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.F_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function alreadyPresent(text) {
+  return new RegExp(`^\\s*${DECLARATION}\\s*$`, 'm').test(text);
+}
+
+function insertIntoExisting(text) {
+  const platformLineRe = /(platform :ios,\s*'[^']+'\s*\n)/;
+  if (!platformLineRe.test(text)) return null;
+
+  return text.replace(platformLineRe, `$1${DECLARATION}\n`);
+}
+
+function seedTemplate() {
+  return (
+    '# DO NOT MODIFY -- auto-generated by Apache Cordova\n' +
+    "platform :ios, '15.0'\n" +
+    `${DECLARATION}\n` +
+    "target 'App' do\n" +
+    "\tproject 'App.xcodeproj'\n" +
+    'end\n'
+  );
+}
+
+module.exports = function (context) {
+  const opts = (context && context.opts) || {};
+  // HooksRunner.fire() normalizes `opts.cordova.platforms` for every hook type
+  // (see cordova-lib/src/hooks/HooksRunner.js). `opts.platforms` is only ever set
+  // by the `prepare` command itself (before_prepare/after_prepare) -- for
+  // before_plugin_install/after_plugin_install (fired during `cordova plugin add`,
+  // including plugin restoration onto a freshly added platform) the platform list
+  // only exists at `opts.cordova.platforms`. Check both so this hook actually runs
+  // on every path that can trigger `pod install`.
+  const platformsList = (opts.cordova && opts.cordova.platforms) || opts.platforms || [];
+  if (!platformsList.includes('ios')) return;
+
+  const projectRoot =
+    opts.projectRoot ||
+    (opts.cordova && opts.cordova.project && opts.cordova.project.root) ||
+    null;
+
+  if (!projectRoot) return;
+
+  const iosPlatformDir = path.join(projectRoot, 'platforms', 'ios');
+  if (!exists(iosPlatformDir)) return;
+
+  const podfilePath = path.join(iosPlatformDir, 'Podfile');
+
+  let result;
+  let action;
+
+  if (exists(podfilePath)) {
+    const original = fs.readFileSync(podfilePath, 'utf8');
+    if (alreadyPresent(original)) {
+      action = 'already-present';
+      result = original;
+    } else {
+      const patched = insertIntoExisting(original);
+      if (!patched) {
+        // eslint-disable-next-line no-console
+        console.log('cordova-plugin-reteno: iOS setup: Podfile format not recognized, skipping use_modular_headers! patch.');
+        return;
+      }
+      action = 'patched';
+      result = patched;
+    }
+  } else {
+    action = 'seeded';
+    result = seedTemplate();
+  }
+
+  if (action !== 'already-present') {
+    fs.writeFileSync(podfilePath, result, 'utf8');
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`cordova-plugin-reteno: iOS setup: Podfile use_modular_headers!=${action}.`);
+};

package/scripts/validate-install.js

@@ -79,17 +79,45 @@ module.exports = function (context) {
     (opts.options && opts.options.options && opts.options.options.cli_variables) ||
     {};
 
-  const accessKey =
-    variables.SDK_ACCESS_KEY ||
-    readVarFromCmdLine('SDK_ACCESS_KEY') ||
-    readVarFromPackageJson('SDK_ACCESS_KEY') ||
-    process.env.SDK_ACCESS_KEY;
-  const accessKeyStr = accessKey == null ? '' : String(accessKey).trim();
+  function firstValidValue(candidates) {
+    for (const candidate of candidates) {
+      const value = candidate == null ? '' : String(candidate).trim();
+      if (
+        value.length > 0 &&
+        value !== 'MISSING' &&
+        value !== '$RETENO_ACCESS_KEY' &&
+        value !== '$SDK_ACCESS_KEY'
+      ) {
+        return value;
+      }
+    }
+    return '';
+  }
 
-  if (accessKeyStr.length === 0 || accessKeyStr === 'MISSING') {
+  const retenoAccessKey = firstValidValue([
+    variables.RETENO_ACCESS_KEY,
+    readVarFromCmdLine('RETENO_ACCESS_KEY'),
+    readVarFromPackageJson('RETENO_ACCESS_KEY'),
+    process.env.RETENO_ACCESS_KEY,
+  ]);
+  const legacyAccessKey = firstValidValue([
+    variables.SDK_ACCESS_KEY,
+    readVarFromCmdLine('SDK_ACCESS_KEY'),
+    readVarFromPackageJson('SDK_ACCESS_KEY'),
+    process.env.SDK_ACCESS_KEY,
+  ]);
+  const accessKey = retenoAccessKey || legacyAccessKey;
+
+  if (!accessKey) {
     throw new Error(
-      'cordova-plugin-reteno: SDK_ACCESS_KEY is required. Install with: ' +
-        'cordova plugin add cordova-plugin-reteno --variable SDK_ACCESS_KEY=YOUR_KEY'
+      'cordova-plugin-reteno: RETENO_ACCESS_KEY is required. Install with: ' +
+        'cordova plugin add cordova-plugin-reteno --variable RETENO_ACCESS_KEY=YOUR_KEY'
+    );
+  }
+
+  if (!retenoAccessKey && legacyAccessKey) {
+    console.warn(
+      'cordova-plugin-reteno: SDK_ACCESS_KEY is deprecated; use RETENO_ACCESS_KEY instead.'
     );
   }
 };

package/src/android/app/build.gradle

@@ -1,6 +1,6 @@
 apply plugin: 'com.android.application'
 
-def retenoFcmVersion = '2.10.1'
+def retenoFcmVersion = '2.10.2'
 
 android {
     namespace 'com.reteno.plugin'

package/src/android/app/src/main/java/com/reteno/plugin/RetenoPlugin.java

@@ -68,7 +68,8 @@ import java.util.Map;
 public class RetenoPlugin extends CordovaPlugin {
   private static final int REQ_CODE_POST_NOTIFICATIONS = 10001;
   private static final String PERMISSION_POST_NOTIFICATIONS = "android.permission.POST_NOTIFICATIONS";
-  private static final String SDK_ACCESS_KEY_META = "com.reteno.SDK_ACCESS_KEY";
+  private static final String RETENO_ACCESS_KEY_META = "com.reteno.RETENO_ACCESS_KEY";
+  private static final String LEGACY_SDK_ACCESS_KEY_META = "com.reteno.SDK_ACCESS_KEY";
 
   private static volatile RetenoPlugin activeInstance;
 
@@ -561,9 +562,9 @@ public class RetenoPlugin extends CordovaPlugin {
       }
       if (TextUtils.isEmpty(accessKey)) {
         callbackContext.error(
-          "Missing SDK_ACCESS_KEY. Provide it when installing the Cordova plugin " +
-          "(e.g. --variable SDK_ACCESS_KEY=YOUR_KEY), pass it to RetenoPlugin.init({accessKey: ...}), " +
-          "or set AndroidManifest meta-data 'com.reteno.SDK_ACCESS_KEY'."
+          "Missing RETENO_ACCESS_KEY. Provide it when installing the Cordova plugin " +
+          "(e.g. --variable RETENO_ACCESS_KEY=YOUR_KEY), pass it to RetenoPlugin.init({accessKey: ...}), " +
+          "or set AndroidManifest meta-data 'com.reteno.RETENO_ACCESS_KEY'."
         );
         return;
       }
@@ -779,7 +780,9 @@ public class RetenoPlugin extends CordovaPlugin {
     if (options == null) {
       return null;
     }
-    String[] keys = new String[] {"accessKey", "access_key", "sdkAccessKey", "SDK_ACCESS_KEY"};
+    String[] keys = new String[] {
+      "accessKey", "access_key", "retenoAccessKey", "RETENO_ACCESS_KEY", "sdkAccessKey", "SDK_ACCESS_KEY"
+    };
     for (String keyName : keys) {
       String raw = options.optString(keyName, null);
       String normalized = normalizeAccessKey(raw);
@@ -1262,12 +1265,18 @@ public class RetenoPlugin extends CordovaPlugin {
       if (info == null || info.metaData == null) {
         return readAccessKeyFromCordovaPreferences();
       }
-      String key = info.metaData.getString(SDK_ACCESS_KEY_META);
+      String key = info.metaData.getString(RETENO_ACCESS_KEY_META);
       String normalized = normalizeAccessKey(key);
       if (normalized != null) {
         return normalized;
       }
 
+      key = info.metaData.getString(LEGACY_SDK_ACCESS_KEY_META);
+      normalized = normalizeAccessKey(key);
+      if (normalized != null) {
+        return normalized;
+      }
+
       return readAccessKeyFromCordovaPreferences();
     } catch (Exception ignored) {
       return readAccessKeyFromCordovaPreferences();
@@ -1276,8 +1285,13 @@ public class RetenoPlugin extends CordovaPlugin {
 
   private String readAccessKeyFromCordovaPreferences() {
     try {
-      String key = this.preferences != null ? this.preferences.getString("SDK_ACCESS_KEY", null) : null;
-      return normalizeAccessKey(key);
+      if (this.preferences == null) {
+        return null;
+      }
+      String key = normalizeAccessKey(this.preferences.getString("RETENO_ACCESS_KEY", null));
+      return key != null
+        ? key
+        : normalizeAccessKey(this.preferences.getString("SDK_ACCESS_KEY", null));
     } catch (Exception ignored) {
       return null;
     }
@@ -1288,7 +1302,7 @@ public class RetenoPlugin extends CordovaPlugin {
       return null;
     }
     key = key.trim();
-    if (key.length() == 0 || "$SDK_ACCESS_KEY".equals(key) || "MISSING".equals(key)) {
+    if (key.length() == 0 || "$RETENO_ACCESS_KEY".equals(key) || "$SDK_ACCESS_KEY".equals(key) || "MISSING".equals(key)) {
       return null;
     }
     return key;

package/src/android/reteno.gradle

@@ -5,7 +5,7 @@ allprojects {
     }
 }
 
-def retenoFcmVersion = '2.10.1'
+def retenoFcmVersion = '2.10.2'
 
 def firebaseMessagingVersion = '23.1.0'
 
@@ -16,7 +16,8 @@ dependencies {
 }
 
 // ---------------------------------------------------------------------------
-// Capacitor: auto-substitute SDK_ACCESS_KEY in the merged plugin manifest.
+// Capacitor: auto-substitute RETENO_ACCESS_KEY (or its legacy alias) in the
+// merged plugin manifest.
 //
 // TODO: Migrate to a dedicated Gradle task with declared inputs/outputs when
 //       Configuration Cache becomes the default in Capacitor. Running file I/O
@@ -24,8 +25,8 @@ dependencies {
 //       executes on every Gradle invocation (including `./gradlew tasks`).
 //
 // Capacitor does NOT resolve $VARIABLE placeholders from plugin.xml; it uses
-// the <preference default="…"> value instead.  For SDK_ACCESS_KEY the default
-// is "MISSING", which makes the SDK fail at runtime.
+// the <preference default="…"> value instead. For access-key preferences the
+// default is "MISSING", which makes the SDK fail at runtime.
 //
 // This block reads the real value from capacitor.config.json (generated by
 // Capacitor CLI from capacitor.config.ts) and patches the manifest source
@@ -49,7 +50,7 @@ try {
     new File(project.projectDir, 'src/main/AndroidManifest.xml'),  // when applied from the plugin module itself
   ]
   for (def f : manifestCandidates) {
-    if (f.exists() && f.text.contains('com.reteno.SDK_ACCESS_KEY')) {
+    if (f.exists() && (f.text.contains('com.reteno.RETENO_ACCESS_KEY') || f.text.contains('com.reteno.SDK_ACCESS_KEY'))) {
       capPluginManifest = f
       break
     }
@@ -71,16 +72,25 @@ try {
     def slurper = new groovy.json.JsonSlurper()
     def config = slurper.parse(capConfigJson)
     def prefs = config?.cordova?.preferences
-    def accessKey = prefs?.SDK_ACCESS_KEY?.toString()?.trim()
+    def normalizeAccessKey = { value ->
+      def key = value?.toString()?.trim()
+      return key != null && key.length() > 0 && key != 'MISSING' && key != '$RETENO_ACCESS_KEY' && key != '$SDK_ACCESS_KEY'
+        ? key
+        : null
+    }
+    def retenoAccessKey = normalizeAccessKey(prefs?.RETENO_ACCESS_KEY)
+    def legacyAccessKey = normalizeAccessKey(prefs?.SDK_ACCESS_KEY)
+    def accessKey = retenoAccessKey ?: legacyAccessKey
+    def manifestKey = retenoAccessKey != null ? 'RETENO_ACCESS_KEY' : 'SDK_ACCESS_KEY'
 
-    if (accessKey != null && accessKey.length() > 0 && accessKey != 'MISSING' && accessKey != '$SDK_ACCESS_KEY') {
+    if (accessKey != null) {
       def manifestText = capPluginManifest.text
-      def pattern = ~/(<meta-data\s+android:name="com\.reteno\.SDK_ACCESS_KEY"\s+android:value=")([^"]*?)(")/
+      def pattern = ~/(<meta-data\s+android:name="com\.reteno\.${manifestKey}"\s+android:value=")([^"]*?)(")/
       def matcher = pattern.matcher(manifestText)
       if (matcher.find() && matcher.group(2) != accessKey) {
         def patched = matcher.replaceFirst('$1' + java.util.regex.Matcher.quoteReplacement(accessKey) + '$3')
         capPluginManifest.text = patched
-        logger.lifecycle("cordova-plugin-reteno: Patched SDK_ACCESS_KEY in Capacitor plugin manifest.")
+        logger.lifecycle("cordova-plugin-reteno: Patched ${manifestKey} in Capacitor plugin manifest.")
       }
     }
   }

package/src/ios/RetenoPlugin.swift

@@ -11,6 +11,7 @@ import FirebaseMessaging
 @objc(RetenoPlugin)
 class RetenoPlugin: CDVPlugin {
   private static weak var activeInstance: RetenoPlugin?
+  private static var hasStartedDelayedInitialization = false
   private var inboxCountCallbackId: String?
   private var isManualTokenMode = false
   #if canImport(FirebaseMessaging)
@@ -21,6 +22,10 @@ class RetenoPlugin: CDVPlugin {
 
   override func pluginInitialize() {
     RetenoPlugin.activeInstance = self
+    // The Objective-C bootstrap normally calls this from AppDelegate's
+    // didFinishLaunchingWithOptions. Keep this call as an idempotent fallback
+    // for unusual hosts that replace or bypass UIApplication's delegate setup.
+    RetenoPlugin.delayedStartIfNeeded()
     #if canImport(FirebaseMessaging)
     if let messaging = messagingIfAvailable() {
       messaging.delegate = self
@@ -28,6 +33,15 @@ class RetenoPlugin: CDVPlugin {
     #endif
   }
 
+  /// Called by RetenoPluginBootstrap from didFinishLaunchingWithOptions.
+  /// The Objective-C entry point lets Cordova and Capacitor start notification
+  /// response buffering before either framework lazily creates the plugin.
+  @objc static func delayedStartIfNeeded() {
+    guard !hasStartedDelayedInitialization else { return }
+    hasStartedDelayedInitialization = true
+    Reteno.delayedStart()
+  }
+
   override func onAppTerminate() {
     if RetenoPlugin.activeInstance === self {
       RetenoPlugin.activeInstance = nil
@@ -42,12 +56,14 @@ class RetenoPlugin: CDVPlugin {
   func initialize(_ command: CDVInvokedUrlCommand) {
     let options = (command.arguments.first as? [String: Any]) ?? [:]
 
-    let providedKey = (options["accessKey"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
-    let preferenceKey = getPreference("sdk_access_key")?.trimmingCharacters(in: .whitespacesAndNewlines)
-    let accessKey = (providedKey?.isEmpty == false) ? providedKey : preferenceKey
+    let providedKey = normalizedAccessKey(options["accessKey"] as? String)
+    let retenoPreferenceKey = normalizedAccessKey(getPreference("reteno_access_key"))
+    let legacyPreferenceKey = normalizedAccessKey(getPreference("sdk_access_key"))
+    let preferenceKey = retenoPreferenceKey ?? legacyPreferenceKey
+    let accessKey = providedKey ?? preferenceKey
 
     guard let apiKey = accessKey, !apiKey.isEmpty else {
-      sendError("Missing SDK access key. Provide options.accessKey or set preference SDK_ACCESS_KEY.", to: command)
+      sendError("Missing SDK access key. Provide options.accessKey or set preference RETENO_ACCESS_KEY.", to: command)
       return
     }
 
@@ -131,7 +147,12 @@ class RetenoPlugin: CDVPlugin {
     self.isManualTokenMode = (deviceTokenMode == .manual)
 
     DispatchQueue.main.async {
-      Reteno.start(apiKey: apiKey, deviceTokenHandlingMode: deviceTokenMode, configuration: configuration)
+      // delayedSetup (paired with delayedStartIfNeeded() during native bootstrap)
+      // completes initialization and replays any push response buffered since
+      // launch -- e.g. a push-linked in-app opened while the SDK was still
+      // cold-starting. Requires delayedStart() to have run first, or this is a
+      // silent no-op (see Reteno.delayedSetup's IsDelayedInitialization guard).
+      Reteno.delayedSetup(apiKey: apiKey, deviceTokenHandlingMode: deviceTokenMode, configuration: configuration)
 
       // When IOS_DEVICE_TOKEN_HANDLING_MODE is manual and FirebaseMessaging is available,
       // configure Firebase if the developer hasn't done it yet, then hook FCM
@@ -1331,6 +1352,17 @@ class RetenoPlugin: CDVPlugin {
     return nil
   }
 
+  private func normalizedAccessKey(_ key: String?) -> String? {
+    guard let value = key?.trimmingCharacters(in: .whitespacesAndNewlines),
+          !value.isEmpty,
+          value != "MISSING",
+          value != "$RETENO_ACCESS_KEY",
+          value != "$SDK_ACCESS_KEY" else {
+      return nil
+    }
+    return value
+  }
+
   private func sendError(_ message: String, to command: CDVInvokedUrlCommand) {
     let result = CDVPluginResult(status: CDVCommandStatus_ERROR, messageAs: message)
     commandDelegate.send(result, callbackId: command.callbackId)