feat(branch-io): sync wrapper with branch-cordova-sdk v6.6.1 API

Add missing methods (enableTestMode, setLogging, getStandardEvents, crossPlatformIds, lastAttributedTouchData, getBranchQRCode, setDMAParamsForEEA, setConsumerProtectionAttributionLevel, setSDKWaitTimeForThirdPartyAPIs, setAnonID, setODMInfo), fix setRequestMetadata's signature (now requires key/val), and mark methods removed upstream (setDebug, userCompletedAction, loadRewards, redeemRewards, creditHistory, initSessionWithCallback) as @deprecated.
2026-08-04 00:00:08 +08:00 · 2026-07-27 22:19:11 +02:00
2 changed files with 190 additions and 239 deletions
@@ -1,196 +1,18 @@
 import { Cordova, AwesomeCordovaNativePlugin, Plugin } from '@awesome-cordova-plugins/core';
 import { Injectable } from '@angular/core';

-/**
- * Authorization status of the Background Fetch API. Returned by `BackgroundFetch#configure` and `BackgroundFetch#status`.
- *
- * @since 7.0.0
- */
-export enum BackgroundFetchStatus {
-  /**
-   * Background fetch updates are unavailable and the user cannot enable them again.
-   * For example, this status can occur when parental controls are in effect for the current user.
-   */
-  STATUS_RESTRICTED = 0,
-  /**
-   * The user explicitly disabled background behavior for this app or for the whole system.
-   */
-  STATUS_DENIED = 1,
-  /**
-   * Background fetch is available and enabled.
-   */
-  STATUS_AVAILABLE = 2,
-}
-
-/**
- * [Android only] Network type constraint for scheduled tasks. Used with `BackgroundFetchConfig#requiredNetworkType`
- * and `BackgroundFetchTaskConfig#requiredNetworkType`.
- *
- * @since 7.0.0
- */
-export enum BackgroundFetchNetworkType {
-  /**
-   * No network constraint. The task will run regardless of network state.
-   */
-  NONE = 0,
-  /**
-   * The task requires any active network connection.
-   */
-  ANY = 1,
-  /**
-   * The task requires an unmetered (e.g. Wi-Fi) network connection.
-   */
-  UNMETERED = 2,
-  /**
-   * The task requires a non-roaming network connection.
-   */
-  NOT_ROAMING = 3,
-  /**
-   * The task requires a cellular (mobile data) network connection.
-   */
-  CELLULAR = 4,
-}
-
-/**
- * Configuration properties shared by both `BackgroundFetchConfig` and `BackgroundFetchTaskConfig`.
- *
- * Aside from `stopOnTerminate`, all properties are Android-only. iOS manages background execution
- * through its own system-controlled Background Fetch mechanism and does not support these constraints.
- */
-export interface BackgroundFetchAbstractConfig {
+export interface BackgroundFetchConfig {
  /**
   * Set true to cease background-fetch from operating after user "closes" the app. Defaults to true.
   */
  stopOnTerminate?: boolean;
-
-  /**
-   * [Android only] Set `true` to initiate background-fetch events when the device is rebooted. Defaults to `false`.
-   * NOTE: `startOnBoot` requires `stopOnTerminate: false`.
-   *
-   * @since 7.0.0
-   */
-  startOnBoot?: boolean;
-
-  /**
-   * [Android only] Set `true` to enable the Headless mechanism for handling fetch events after app termination.
-   * Defaults to `false`. NOTE: Requires `stopOnTerminate: false`.
-   *
-   * @since 7.0.0
-   */
-  enableHeadless?: boolean;
-
-  /**
-   * [Android only] By default, the plugin uses Android's `JobScheduler` when possible and falls back to
-   * `AlarmManager` for older devices. Set `true` to always use `AlarmManager` regardless of API level.
-   * Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  forceAlarmManager?: boolean;
-
-  /**
-   * [Android only] Specify the kind of network connectivity required to run this task. Defaults to
-   * `BackgroundFetchNetworkType.NONE`.
-   *
-   * @since 7.0.0
-   */
-  requiredNetworkType?: BackgroundFetchNetworkType;
-
-  /**
-   * [Android only] Set `true` to require the device's battery level to be above the "low battery" threshold
-   * before running this task. Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresBatteryNotLow?: boolean;
-
-  /**
-   * [Android only] Set `true` to require the device's available storage to be above the "low storage"
-   * threshold before running this task. Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresStorageNotLow?: boolean;
-
-  /**
-   * [Android only] Set `true` to require the device to be charging (or connected to permanent power, such
-   * as an Android TV device) before running this task. Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresCharging?: boolean;
-
-  /**
-   * [Android only] Set `true` to require the device to be idle (not actively used) before running this task.
-   * Defaults to `false`.
-   *
-   * @since 7.0.0
-   */
-  requiresDeviceIdle?: boolean;
-}
-
-export interface BackgroundFetchConfig extends BackgroundFetchAbstractConfig {
-  /**
-   * The minimum interval in **minutes** between background-fetch events. Defaults to `15` minutes. The
-   * minimum allowed value is `15` minutes.
-   *
-   * NOTE: The OS does not guarantee fetch events will fire at exactly this interval. iOS adjusts the
-   * interval based on usage patterns and system conditions. This value is a *minimum*, not a schedule.
-   *
-   * @since 7.0.0
-   */
-  minimumFetchInterval?: number;
-}
-
-/**
- * Configuration for a custom scheduled task, provided to `BackgroundFetch#scheduleTask`.
- *
- * @since 7.0.0
- */
-export interface BackgroundFetchTaskConfig extends BackgroundFetchAbstractConfig {
-  /**
-   * A unique identifier for this task. Use the same `taskId` with `BackgroundFetch#finish` to signal
-   * completion and with `BackgroundFetch#stopTask` to cancel it. Use reverse-domain notation to avoid
-   * collisions (e.g. `'com.foo.sync'`).
-   */
-  taskId: string;
-
-  /**
-   * The minimum delay in **milliseconds** before this task runs.
-   *
-   * NOTE: On iOS, the system may delay the task beyond this value depending on device conditions. On
-   * Android, `JobScheduler` treats this as a minimum delay.
-   */
-  delay: number;
-
-  /**
-   * Set `true` to schedule a repeating task. Defaults to `false` (one-shot).
-   */
-  periodic?: boolean;
-
-  /**
-   * [iOS only] Set `true` to require a network connection before running this task. On Android, use
-   * `requiredNetworkType` instead.
-   */
-  requiresNetworkConnectivity?: boolean;
 }

 /**
 * @name Background Fetch
 * @description
- * Cross-platform Background Fetch implementation. This plugin will execute your provided callbackFn
- * whenever a background-fetch event occurs.
- *
- * ### iOS
- * There is no way to increase the rate which a fetch-event occurs and this plugin sets the rate to the
- * most frequent possible value -- iOS determines the rate automatically based upon device usage and
- * time-of-day (ie: fetch-rate is about ~15min during prime-time hours; less frequently when the user is
- * presumed to be sleeping).
- *
- * ### Android
- * Uses `JobScheduler` (API 21+) or `AlarmManager` to schedule periodic callbacks. Additional constraints
- * (network, charging, idle) can be set via `BackgroundFetchConfig`.
- *
+ * iOS Background Fetch Implementation. See: https://developer.apple.com/reference/uikit/uiapplication#1657399
+ * iOS Background Fetch is basically an API which wakes up your app about every 15 minutes (during the user's prime-time hours) and provides your app exactly 30s of background running-time. This plugin will execute your provided callbackFn whenever a background-fetch event occurs. There is no way to increase the rate which a fetch-event occurs and this plugin sets the rate to the most frequent possible value of UIApplicationBackgroundFetchIntervalMinimum -- iOS determines the rate automatically based upon device usage and time-of-day (ie: fetch-rate is about ~15min during prime-time hours; less frequently when the user is presumed to be sleeping, at 3am for example).
 * For more detail, please see https://github.com/transistorsoft/cordova-plugin-background-fetch
 * @usage
 *
@@ -201,23 +23,17 @@ export interface BackgroundFetchTaskConfig extends BackgroundFetchAbstractConfig
 * constructor(private backgroundFetch: BackgroundFetch) {
 *
 *   const config: BackgroundFetchConfig = {
- *     minimumFetchInterval: 15,
 *     stopOnTerminate: false, // Set true to cease background-fetch from operating after user "closes" the app. Defaults to true.
 *   }
 *
- *   backgroundFetch.configure(config, (taskId: string) => {
+ *   backgroundFetch.configure(config)
+ *      .then(() => {
+ *          console.log('Background Fetch initialized');
 *
- *          console.log('Background Fetch event received', taskId);
+ *          this.backgroundFetch.finish();
 *
- *          this.backgroundFetch.finish(taskId);
- *
- *   }, (taskId: string) => {
- *          // OS has signalled that remaining background time is about to expire.
- *          console.log('Background Fetch TIMEOUT', taskId);
- *          this.backgroundFetch.finish(taskId);
- *   }).then((status) => {
- *          console.log('Background Fetch initialized', status);
- *   }).catch(e => console.log('Error initializing background fetch', e));
+ *      })
+ *      .catch(e => console.log('Error initializing background fetch', e));
 *
 *   // Start the background-fetch API. Your callbackFn provided to #configure will be executed each time a background-fetch event occurs. NOTE the #configure method automatically calls #start. You do not have to call this method after you #configure the plugin
 *   backgroundFetch.start();
@@ -231,38 +47,26 @@ export interface BackgroundFetchTaskConfig extends BackgroundFetchAbstractConfig
 * ```
 * @interfaces
 * BackgroundFetchConfig
- * BackgroundFetchTaskConfig
 */
@Plugin({
  pluginName: 'BackgroundFetch',
  plugin: 'cordova-plugin-background-fetch',
  pluginRef: 'BackgroundFetch',
  repo: 'https://github.com/transistorsoft/cordova-plugin-background-fetch',
-  platforms: ['Android', 'iOS'],
+  platforms: ['iOS'],
 })
@Injectable()
 export class BackgroundFetch extends AwesomeCordovaNativePlugin {
  /**
-   * Configures the plugin's fetch callbackFn.
-   *
-   * Calling `configure` automatically starts background-fetch (equivalent to calling `#start` immediately
-   * after configuration).
+   * Configures the plugin's fetch callbackFn
   *
   * @param {BackgroundFetchConfig} config Configuration for plugin
-   * @param {Function} [onEvent] Callback fired when a background-fetch event is received. The `taskId`
-   * string identifies which task fired -- pass it to `#finish` when done. Required as of plugin `7.0.0`.
-   * @param {Function} [onTimeout] Callback fired when the OS signals that remaining background time is
-   * about to expire. Call `#finish` immediately. Added in plugin `7.0.0`.
   * @returns {Promise<any>}
   */
  @Cordova({
-    otherPromise: true,
+    callbackOrder: 'reverse',
  })
-  configure(
-    config: BackgroundFetchConfig,
-    onEvent?: (taskId: string) => void,
-    onTimeout?: (taskId: string) => void
-  ): Promise<any> {
+  configure(config: BackgroundFetchConfig): Promise<any> {
    return;
  }

@@ -306,33 +110,4 @@ export class BackgroundFetch extends AwesomeCordovaNativePlugin {
  status(): Promise<any> {
    return;
  }
-
-  /**
-   * Schedule a custom one-shot or periodic background task in addition to the default fetch callback
-   * registered with `#configure`.
-   *
-   * Custom tasks fire the same callback registered via `#configure`'s `onEvent` argument, with their
-   * unique `taskId`. Use `#finish` with that `taskId` to signal completion.
-   *
-   * @param {BackgroundFetchTaskConfig} config Task configuration, including a unique `taskId` and a
-   * minimum `delay` in milliseconds.
-   * @returns {Promise<any>}
-   * @since 7.0.0
-   */
-  @Cordova()
-  scheduleTask(config: BackgroundFetchTaskConfig): Promise<any> {
-    return;
-  }
-
-  /**
-   * Cancel a specific task previously scheduled via `#scheduleTask`, identified by its `taskId`.
-   *
-   * @param taskId The identifier of the scheduled task to stop.
-   * @returns {Promise<any>}
-   * @since 7.0.0
-   */
-  @Cordova()
-  stopTask(taskId: string): Promise<any> {
-    return;
-  }
 }
@@ -36,6 +36,40 @@ export interface BranchIoProperties {
  [x: string]: any;
 }

+export interface BranchIoQRCodeSettings {
+  codeColor?: string;
+  backgroundColor?: string;
+  centerLogo?: string;
+  width?: number;
+  margin?: number;
+  imageFormat?: 'PNG' | 'JPEG';
+  [x: string]: any;
+}
+
+export interface BranchIoStandardEvents {
+  STANDARD_EVENT_ADD_TO_CART: string;
+  STANDARD_EVENT_ADD_TO_WISHLIST: string;
+  STANDARD_EVENT_VIEW_CART: string;
+  STANDARD_EVENT_INITIATE_PURCHASE: string;
+  STANDARD_EVENT_ADD_PAYMENT_INFO: string;
+  STANDARD_EVENT_PURCHASE: string;
+  STANDARD_EVENT_SEARCH: string;
+  STANDARD_EVENT_VIEW_ITEM: string;
+  STANDARD_EVENT_VIEW_ITEMS: string;
+  STANDARD_EVENT_RATE: string;
+  STANDARD_EVENT_SHARE: string;
+  STANDARD_EVENT_INITIATE_STREAM: string;
+  STANDARD_EVENT_COMPLETE_STREAM: string;
+  STANDARD_EVENT_COMPLETE_REGISTRATION: string;
+  STANDARD_EVENT_COMPLETE_TUTORIAL: string;
+  STANDARD_EVENT_ACHIEVE_LEVEL: string;
+  STANDARD_EVENT_UNLOCK_ACHIEVEMENT: string;
+  STANDARD_EVENT_INVITE: string;
+  STANDARD_EVENT_LOGIN: string;
+  STANDARD_EVENT_SUBSCRIBE: string;
+  STANDARD_EVENT_START_TRIAL: string;
+}
+
 export interface BranchUniversalObject {
  generateShortUrl(analytics: BranchIoAnalytics, properties: BranchIoProperties): Promise<any>;
  registerView(): Promise<any>;
@@ -63,6 +97,8 @@ export interface BranchUniversalObject {
 * BranchIoPromise
 * BranchIoAnalytics
 * BranchIoProperties
+ * BranchIoQRCodeSettings
+ * BranchIoStandardEvents
 * BranchUniversalObject
 */
@Plugin({
@@ -77,6 +113,7 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
  /**
   * for development and debugging only
   *
+   * @deprecated since branch-cordova-sdk v6.1.0. Use setLogging instead.
   * @param {boolean} enable Enable debug
   * @returns {Promise<any>}
   */
@@ -85,6 +122,27 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
    return;
  }

+  /**
+   * Enables debug logging in the native layer. Must be called before initSession.
+   *
+   * @param {boolean} enable Enable logging
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true })
+  setLogging(enable: boolean): Promise<any> {
+    return;
+  }
+
+  /**
+   * Enables test mode. Must be called before initSession.
+   *
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true })
+  enableTestMode(): Promise<any> {
+    return;
+  }
+
  /**
   * Disable tracking
   *
@@ -109,6 +167,7 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
  /**
   * Initializes Branch with callback
   *
+   * @deprecated not present in branch-cordova-sdk (absent since at least v3.4.0, still absent in v6.6.1). Use initSession instead.
   * @returns {Observable<any>}
   */
  @Cordova({ observable: true })
@@ -119,10 +178,12 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
  /**
   * Set Request Metadata
   *
+   * @param {string} key
+   * @param {string} val
   * @returns {Promise<any>}
   */
  @Cordova({ otherPromise: true })
-  setRequestMetadata(): Promise<any> {
+  setRequestMetadata(key: string, val: string): Promise<any> {
    return;
  }

@@ -157,6 +218,26 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
    return;
  }

+  /**
+   * Get the cross platform and developer identity data most recently set
+   *
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true })
+  crossPlatformIds(): Promise<any> {
+    return;
+  }
+
+  /**
+   * Get the last attributed touch data
+   *
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true })
+  lastAttributedTouchData(): Promise<any> {
+    return;
+  }
+
  /**
   * Set identy of user
   *
@@ -181,6 +262,7 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
  /**
   * Registers a custom event
   *
+   * @deprecated since branch-cordova-sdk v5.0.0. Use sendBranchEvent instead.
   * @param {string} eventName
   * @param {any} metaData
   * @returns {Promise<any>}
@@ -215,6 +297,16 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
    return;
  }

+  /**
+   * Get the map of Branch standard event names
+   *
+   * @returns {Promise<BranchIoStandardEvents>}
+   */
+  @Cordova({ otherPromise: true })
+  getStandardEvents(): Promise<BranchIoStandardEvents> {
+    return;
+  }
+
  /**
   * create a branchUniversalObj variable to reference with other Branch methods
   *
@@ -226,9 +318,29 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
    return;
  }

+  /**
+   * Generate a Branch QR code as a base64 encoded image
+   *
+   * @param {BranchIoQRCodeSettings} qrCodeSettings
+   * @param {BranchUniversalObject} branchUniversalObject
+   * @param {BranchIoAnalytics} analytics
+   * @param {BranchIoProperties} properties
+   * @returns {Promise<string>}
+   */
+  @Cordova({ otherPromise: true })
+  getBranchQRCode(
+    qrCodeSettings: BranchIoQRCodeSettings,
+    branchUniversalObject: BranchUniversalObject,
+    analytics: BranchIoAnalytics,
+    properties: BranchIoProperties
+  ): Promise<string> {
+    return;
+  }
+
  /**
   * Load credits
   *
+   * @deprecated since branch-cordova-sdk v5.0.0. Branch's Rewards/Credits feature was removed upstream.
   * @param {any} bucket
   * @returns {Promise<any>}
   */
@@ -240,6 +352,7 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
  /**
   * Redeem Rewards
   *
+   * @deprecated since branch-cordova-sdk v5.0.0. Branch's Rewards/Credits feature was removed upstream.
   * @param {string} value
   * @param {any} bucket
   * @returns {Promise<any>}
@@ -252,10 +365,73 @@ export class BranchIo extends AwesomeCordovaNativePlugin {
  /**
   * Show credit history
   *
+   * @deprecated since branch-cordova-sdk v5.0.0. Branch's Rewards/Credits feature was removed upstream.
   * @returns {Promise<any>}
   */
  @Cordova({ otherPromise: true })
  creditHistory(): Promise<any> {
    return;
  }
+
+  /**
+   * Sets Digital Markets Act (DMA) consent parameters for users in the European Economic Area
+   *
+   * @param {boolean} eeaRegion whether the user is in the EEA
+   * @param {boolean} adPersonalizationConsent whether the user has consented to ad personalization
+   * @param {boolean} adUserDataUsageConsent whether the user has consented to ad user data usage
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true })
+  setDMAParamsForEEA(
+    eeaRegion: boolean,
+    adPersonalizationConsent: boolean,
+    adUserDataUsageConsent: boolean
+  ): Promise<any> {
+    return;
+  }
+
+  /**
+   * Sets the Consumer Protection Attribution (CPP) level
+   *
+   * @param {string} level one of 'FULL', 'REDUCED', 'MINIMAL', 'NONE'
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true })
+  setConsumerProtectionAttributionLevel(level: string): Promise<any> {
+    return;
+  }
+
+  /**
+   * Sets the SDK wait time, in seconds, for third party API responses (Google On Device Measurement). iOS only.
+   *
+   * @param {number} waitTime
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true, platforms: ['iOS'] })
+  setSDKWaitTimeForThirdPartyAPIs(waitTime: number): Promise<any> {
+    return;
+  }
+
+  /**
+   * Sets a custom Meta anonymous ID for the current user. iOS only.
+   *
+   * @param {string} anonID
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true, platforms: ['iOS'] })
+  setAnonID(anonID: string): Promise<any> {
+    return;
+  }
+
+  /**
+   * Passes Google On Device Measurement (ODM) event data and the app's first-open timestamp. iOS only.
+   *
+   * @param {string} odmInfo
+   * @param {number} firstOpenTimeStamp
+   * @returns {Promise<any>}
+   */
+  @Cordova({ otherPromise: true, platforms: ['iOS'] })
+  setODMInfo(odmInfo: string, firstOpenTimeStamp: number): Promise<any> {
+    return;
+  }
 }