React to Changes in Customer Journey State

This guide explains how your app can react and modify its state based on changes to your customers' subscription journey.

The Customer Journey describes how a user's purchase relationship with your app changes over time. This is affected by a number of events such as purchases, cancellations, as well as more complex scenarios like free trials and account holds.

Nami models all the signals about a single user and puts these into a single Customer Journey State for each user.

These data are made directly available in your app so you can use them to display a paywall, show an in-app message, or take any other action to engage with your users based on their current subscription status.

There are 2 main ways you can work with the Customer Journey State.

  1. Manually check to see what the current journey state is
  2. Register a callback to react to changes in the customer's journey state

The customer journey state in the SDK is an object with the structure below.

@objc public class CustomerJourneyState:NSObject, NSCoding, Codable {
  let formerSubscriber: Bool
  let inGracePeriod: Bool
  let inTrialPeriod: Bool
  let inIntroOfferPeriod: Bool
@interface CustomerJourneyState : NSObject <NSCoding>
@property (nonatomic, readonly) BOOL formerSubscriber;
@property (nonatomic, readonly) BOOL inGracePeriod;
@property (nonatomic, readonly) BOOL inTrialPeriod;
@property (nonatomic, readonly) BOOL inIntroOfferPeriod;
data class CustomerJourneyState(
  val formerSubscriber: Boolean,
  val inGracePeriod: Boolean,
  val inTrialPeriod: Boolean,
  val inIntroOfferPeriod: Boolean
CustomerJourneyState = {
  "formerSubscriber": Boolean,
  "inGracePeriod": Boolean,
  "inTrialPeriod": Boolean,
  "inIntroOfferPeriod": Boolean
class CustomerJourneyState {
  final bool formerSubscriber;
  final bool inGracePeriod;
  final bool inTrialPeriod;
  final bool inIntroOfferPeriod;
interface CustomerJourneyState : INSCoding {
  bool FormerSubscriber();
  bool InGracePeriod();
  bool InTrialPeriod();
  bool InIntroOfferPeriod();

Nami fetches the most recent journey state at the start of each session. Events like a purchase may also update the journey state immediately after they are complete and verified.

Manually check the current journey state

The Nami SDKs provide a simple method to fetch the current journey state for the user on the device.

let journeyState = NamiCustomerManager.currentCustomerJourneyState()
CustomerJourneyState *journeyState = [NamiCustomerManager currentCustomerJourneyState];
val journeyState = NamiCustomerManager.currentCustomerJourneyState()
CustomerJourneyState journeyState = NamiCustomerManager.currentCustomerJourneyState();
NativeModules.NamiCustomerManagerBridge.currentCustomerJourneyState( (customerJourneyState) => { 
  // react to the journey state
CustomerJourneyState state = await NamiCustomerManager.currentCustomerJourneyState();
var journeyState = NamiCustomerManager.CurrentCustomerJourneyState;

Using a callback to react to changes in journey state

If you do not wish to manually check the customer journey state at specific spots in your code, you might instead want to have your app react only when there's a change to your user's journey state.

Nami offers a callback to enable this use in this case.

The mechanism varies slightly based on how each language works, but generally involves creating a handler or listener that Nami will invoke when a change is detected.

NamiCustomerManager.registerJourneyStateChangedHandler() { newCustomerJourneyState in
  // react to the state here
[NamiCustomerManager registerJourneyStateChangedHandler:^(CustomerJourneyState * _Nonnull newCustomerJourneyState) {
  // react to the state here