SFMC MarketingCloud SDK (Engagement)

Salesforce Marketing Cloud Engagement SDK for React Native — inbox, registration, tags, attributes, analytics.

Installation

yarn add @sfmc/react-native-marketingcloudsdk
# or
npm install @sfmc/react-native-marketingcloudsdk

iOS:

cd ios && pod install

Android: no additional steps — Gradle autolinking discovers the module automatically.

Required SDK configuration

• Android — initialize in your MainApplication.kt via SFMCSdk.configure(...). See the Android SDK Integration Guide.
• iOS — initialize in your AppDelegate.swift via SFMCSdk.initializeSdk(...). See the iOS SDK Integration Guide.
• Configure Firebase (Android) and APNs (iOS) credentials before push will deliver.

Usage

import { MarketingCloudSdkModule } from '@sfmc/react-native-marketingcloudsdk';
import type { MCApi, InboxMessage } from '@sfmc/react-native-marketingcloudsdk';

const mc: MCApi = await MarketingCloudSdkModule.requestSdk();

// Inbox
await mc.refreshInbox();
const allMsgs: InboxMessage[] = await mc.getAllMessages();
const unreadCount = await mc.getUnreadMessageCount();
mc.markMessageRead('message-id');

// Tags + attributes
// The SDK auto-applies a `React` tag on first `requestSdk()` per app process for
// integration segmentation. Call `mc.removeTag('React')` to opt out; it will not
// be re-added within the same process.
mc.addTag('beta-tester');
const tags = await mc.getTags();

// Device id
const deviceId = await mc.getDeviceId();

// Registration callback
mc.setRegistrationCallback();
const emitter = MarketingCloudSdkModule.getEmitter();
const sub = emitter.addListener('sfmc_mc_registration', (registration) => {
  console.log('MC registration changed:', registration);
});

// Cleanup
sub.remove();
mc.unsetRegistrationCallback();

// Inbox response listener (Android only — no-op on iOS)
// Subscribe before starting the native listener so no change is missed.
const inboxSub = emitter.addListener('sfmc_mc_inbox_response', ({ messages }) => {
  console.log('Inbox messages changed:', messages.length);
});
mc.registerInboxResponseListener();

// Cleanup
inboxSub.remove();
mc.unregisterInboxResponseListener();

API

| Method | Return | Description | |--------|--------|-------------| | refreshInbox() | Promise<boolean> | Trigger server inbox refresh | | getAllMessages() | Promise<InboxMessage[]> | Get all inbox messages | | getUnreadMessages() | Promise<InboxMessage[]> | Get unread messages | | getReadMessages() | Promise<InboxMessage[]> | Get read messages | | getDeletedMessages() | Promise<InboxMessage[]> | Get deleted messages | | getMessageCount() | Promise<number> | Total message count | | getUnreadMessageCount() | Promise<number> | Unread message count | | getReadMessageCount() | Promise<number> | Read message count | | getDeletedMessageCount() | Promise<number> | Deleted message count | | markMessageRead(id) | void | Mark a message as read | | markMessageDeleted(id) | void | Mark a message as deleted | | markAllMessagesRead() | void | Mark all messages as read | | markAllMessagesDeleted() | void | Mark all messages as deleted | | trackInboxMessageOpened(message) | void | Track message open analytics (pass the full InboxMessage object) | | addTag(tag) | void | Add a tag | | addTags(tags) | void | Add multiple tags | | removeTag(tag) | void | Remove a tag | | removeTags(tags) | void | Remove multiple tags | | getTags() | Promise<string[]> | Get all tags | | enablePiAnalytics() | void | Enable PI analytics | | disablePiAnalytics() | void | Disable PI analytics | | isPiAnalyticsEnabled() | Promise<boolean> | Check PI analytics state | | enableAnalytics() | void | Enable analytics | | disableAnalytics() | void | Disable analytics | | isAnalyticsEnabled() | Promise<boolean> | Check analytics state | | getDeviceId() | Promise<string \| null> | Get device identifier | | setSignedString(signedString) | Promise<boolean> | Set the signed string security token (pass null to clear) | | getSignedString() | Promise<string \| null> | Get the last stored signed string | | enableLogging() | void | Enable debug logging | | disableLogging() | void | Disable debug logging | | setRegistrationCallback() | void | Start receiving registration change events | | unsetRegistrationCallback() | void | Stop receiving registration change events | | registerInboxResponseListener() | void | Start receiving sfmc_mc_inbox_response events when the inbox message set changes (Android only — no-op on iOS) | | unregisterInboxResponseListener() | void | Stop receiving inbox response events (Android only — no-op on iOS) | | enableLocation() | void | Enable Location (iOS: master location override; Android: geofence messaging — requires ACCESS_FINE_LOCATION + ACCESS_BACKGROUND_LOCATION runtime permissions) | | disableLocation() | void | Disable Location (iOS: master location override; Android: geofence messaging) | | isLocationEnabled() | Promise<boolean> | Check whether Location is enabled | | startWatchingLocation() | void | Start location watching (iOS only — no-op on Android) | | stopWatchingLocation() | void | Stop location watching (iOS only — no-op on Android) | | isWatchingLocation() | Promise<boolean> | Check whether SDK is watching location (iOS only — always false on Android) | | getLastKnownLocation() | Promise<LastKnownLocation \| null> | Last known device location as { latitude?, longitude? } string values (iOS only — always null on Android) | | enableProximityMessaging() | void | Enable proximity (beacon) messaging (Android only — no-op on iOS; requires ACCESS_FINE_LOCATION + ACCESS_BACKGROUND_LOCATION runtime permissions) | | disableProximityMessaging() | void | Disable proximity (beacon) messaging (Android only — no-op on iOS) | | isProximityMessagingEnabled() | Promise<boolean> | Check whether proximity messaging is enabled (Android only — always false on iOS) |

Location & proximity — platform notes

• iOS: enableLocation() is the master location toggle — it governs geofence messaging, coordinate watching (startWatchingLocation), and proximity (beacon) messaging as a single switch. There is no separate proximity call on iOS; enableProximityMessaging() is a no-op.
• Android: enableLocation() enables geofence messaging only. Proximity (beacon) messaging is a separate switch — call enableProximityMessaging() to enable it. Both APIs require the ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION runtime permissions; request and grant them before calling either enable method.

Events

| Event Name | Payload | Description | |------------|---------|-------------| | sfmc_mc_registration | Registration dictionary | Emitted when registration state changes | | sfmc_mc_inbox_response | { messages: InboxMessage[] } | Emitted when the inbox message set changes, after registerInboxResponseListener() (Android only — never emitted on iOS) |

Notes

Installing this package auto-resolves the shared sfmc-core, push, and iam packages — install once, get all of them.

MCModule is exported as an alias for MarketingCloudSdkModule. Both reference the same module.

Versions

• React Native: 0.85.1 (New Architecture mandatory)
• Android: sfmcsdk 3.1.0, marketingcloudsdk 11.0.0
• iOS: MarketingCloudSDK 11.0.0, MarketingCloud-SFMCSdk 4.0.1

License

BSD 3-Clause. See LICENSE for details.