[Feature]: Add configurable timeout for getContentCards() method

[glc-helmbarki]

What problem are you facing?

The getContentCards() method currently lacks a built-in timeout mechanism, which can lead to indefinite loading states in poor network conditions.

// This promise can hang indefinitely
const cards = await Braze.getContentCards();

• No timeout parameter available
• No automatic rejection after X seconds
• Forces developers to implement manual timeout workarounds

In production apps, users on slow connections (3G, congested networks, corporate firewalls) may experience:

• Infinite loading spinners
• Poor user experience
• Unable to access cached content while waiting

Workarounds

We're forced to implement manual timeouts:

 timeoutRef.current = setTimeout(() => setIsLoading(false), 5000);

Ideal Solution

// Option 1: Global configuration
Braze.configure({
  contentCardsTimeout: 5000 // milliseconds
});

// Option 2: Per-call configuration
const cards = await Braze.getContentCards({
  timeout: 5000
});

// Option 3: Separate method
const cards = await Braze.getContentCardsWithTimeout(5000);

Add native timeout support with:

• Configurable duration
• Proper error handling
• Fallback to cache on timeout
• Clear timeout vs network error distinction## Additional Context

Other Information

Many other SDKs provide timeout mechanisms:

• Firebase: Configurable timeouts
• Segment: 30s default timeout
• Amplitude: Built-in retry with backoff

This feature would greatly improve developer experience and app reliability.

1. Using only getCachedContentCards() - But we need fresh data
2. Event-based approach - Still no guarantee of response
3. Manual Promise.race() - Works but feels like a hack

Would the team consider adding this feature? Happy to contribute a PR if you provide guidance on the preferred approach.

[jerielng]

Hey @glc-helmbarki thanks for the thoughtful input in this feature request. Our team is actively assessing ways to improve the predictability of our APIs, such as the example you provided here. For full transparency, such overhauls to our APIs may have a longer time horizon.

To help raise signal for this feature, could you raise some product feedback here?

Thank you!

[asugai]

Adding a 👍 on this issue because we are facing a related issue with a similar solution: Android getContentCards() hangs indefinitely when Content Cards are disabled

Problem

On Android, when Content Cards are disabled in the Braze dashboard, calling Braze.getContentCards() never resolves. The promise hangs indefinitely because:

1. getContentCards() subscribes to ContentCardsUpdatedEvent and waits for it to fire
2. When Content Cards are disabled, the ContentCardsUpdatedEvent is never fired
3. The promise never resolves, causing the app to hang

This differs from iOS behavior, where the SDK fires a notification with a success/failure indicator (ABKContentCardsProcessedIsSuccessfulKey).

Current Android Implementation

  fun getContentCards(promise: Promise) {
      braze.subscribeToContentCardsUpdates(IEventSubscriber { message ->
          promise.resolve(mapContentCards(message.allCards))
          updateContentCardsIfNeeded(message)
      })
      braze.requestContentCardsRefresh()
  }

Proposed Fix

Add a timeout mechanism that resolves with cached cards if no event is received within 5 seconds:

  fun getContentCards(promise: Promise) {
      val timeoutMs = 5000L
      var hasResolved = false
      val handler = Handler(Looper.getMainLooper())

      val timeoutRunnable = Runnable {
          if (!hasResolved) {
              hasResolved = true
              // Return cached cards on timeout (Content Cards may be disabled)
              contentCardsLock.withLock {
                  promise.resolve(mapContentCards(contentCards))
              }
          }
      }

      braze.subscribeToContentCardsUpdates(IEventSubscriber { message ->
          if (!hasResolved) {
              hasResolved = true
              handler.removeCallbacks(timeoutRunnable)
              promise.resolve(mapContentCards(message.allCards))
              updateContentCardsIfNeeded(message)
          }
      })

      handler.postDelayed(timeoutRunnable, timeoutMs)
      braze.requestContentCardsRefresh()
  }

Environment

• @braze/react-native-sdk: 18.0.0
• Android

Workaround

We're currently using patch-package to apply this fix locally.

[sircelsius]

thanks for the signal and suggestion @asugai !

As @jerielng mentioned, we are planning a larger overhaul of our APIs across SDKs in an effort to be more transparent and predictable when we perform asynchronous operations.

Since we expect this rework to be a relatively long process, we will look into timing out these calls as you have suggested as an interim solution!

[jmazursky-phantom]

My team is also experiencing this issue and have had to implement manual timeouts. This feature would be helpful to us as well. However, I would also like some insight in to why the promise sometimes does not resolve. We sometimes experience promises that don't resolve within 30 seconds even under favorable network conditions.

[jerielng]

Thanks for the input @jmazursky-phantom! We are taking these considerations into account and will keep you updated on any API additions.

In your case, there could possibly be other factors at play, such as rate limits under heavy API usage. To determine the cause, you would need to collect some verbose logs from a reproduction and send them in to support@braze.com. Thanks!