Overview

In this article, you'll learn how the Cordial mobile SDKs track screens, and what you need to do to make your app's screens available for in-app message targeting. This article covers the app setup: which screens the SDK tracks, how it names them, and how to change that. Learn more about targeting messages to screens here.

Requirements

• Cordial Android SDK 4.25.0 or later
• Cordial iOS SDK 5.8.1 or later
• Screen targeting enabled for your account. Reach out to your CSM for enablement.

What's tracked automatically

Native apps do not require any  code. Once the SDK is initialized, it tracks:

• Android — every Activity that resumes, and every Fragment that resumes inside a FragmentActivity
• iOS — every UIViewController that appears

How screen names are generated

The SDK derives each name from the class name in two steps: it strips the suffix (Activity, Fragment, or FragmentActivity on Android; ViewController on iOS), then adds a space at each lowercase-to-uppercase boundary.

These are the names you’ll see in the location picker, so class names that read well, produce screen names that read well.

Set custom screen names

Call setScreenMapping during SDK configuration to override the derived names. Write each name exactly as you want it to appear in the platform.

Android

CordialApiConfiguration.getInstance().inAppMessages.screenTargeting.setScreenMapping(
  mapOf(
    CartActivity::class.java to "Cart",
    OrderConfirmationFragment::class.java to "Order Confirmation"
  )
)

iOS

InAppScreenTargetingConfig.shared.setScreenMapping([
  CartViewController.self: "Cart",
  OrderConfirmationViewController.self: "Order Confirmation"
])

iOS also accepts class names as strings, which is the form to use from Objective-C:

[InAppScreenTargetingConfig.shared setScreenMapping:@{
  @"CartViewController": @"Cart"
}];

Restrict tracking to mapped screens

By default the SDK tracks every screen and your mapping only renames some of them. Pass isExclusive to track only the screens you've mapped. This is how you limit reporting to the handful of screens your campaigns actually use.

Android

CordialApiConfiguration.getInstance().inAppMessages.screenTargeting.setScreenMapping(
  mapOf(CartActivity::class.java to "Cart"),
  isExclusive = true
)

iOS

InAppScreenTargetingConfig.shared.setScreenMapping(
  [CartViewController.self: "Cart"],
  isExclusive: true
)

How a targeted message displays

• When a message is ready to display, the SDK compares the active screen against the message's target screens. On a match it displays; otherwise it keeps the message cached and re-checks on every screen change.
• The active screen is verified once more immediately before display, so a message triggered during rapid navigation — a deep link pushing several screens at once, for example — can't land on the wrong screen.
• Matching ignores case and surrounding whitespace.
• Each message displays once, however many times the contact returns to a target screen.
• Messages with no target screens are unaffected and display as they always have.

When screens are reported to Cordial

The SDK counts screen views during a session and sends them when the app goes to the background — one crdl_screen_view event per screen visited:

crdl_screen_view

properties: {
  screen: "Product Detail",
  type: "screen",
  count: 7
}

Counts reset with each session. These events populate the location picker in the dashboard, which reflects the last 30 days.

What's never tracked

• Dialogs and bottom sheets — on Android, anything extending DialogFragment
• iOS container controllers: UINavigationController, UITabBarController, UIPageViewController, UISplitViewController
• Framework and system classes — android., androidx., and com.google.android. on Android; view controllers from outside your app's bundle on iOS
• Cordial's own in-app message screens
• On Android, any Activity listed in disallowedActivities

Troubleshooting

• No locations appear in the dashboard. 
  • Screens are reported when the app goes to the background, so background the app at least once and allow time for processing. Confirm the SDK meets the minimum version.
• A screen is missing from the picker. 
  • Check that it isn't excluded (see What's never tracked), and that you aren't using isExclusive with a mapping that leaves it out.
• The screen name looks wrong. 
  • Derived names come from class names. Use setScreenMapping to override.
• A targeted message doesn't display. 
  • Compare the target screen in the dashboard against what the SDK logs. Every tracked screen change logs Screen changed: <name> at info level.