Version

Troubleshooting

If you're having trouble with the SDK, here are some basic steps to troubleshoot your problems, and solutions to some known issues.

Basic troubleshooting steps

Troubleshooting issues with our MCP server

Our MCP server includes an integration tool that can help troubleshoot your implementation, including problems with push and in-app notifications. It has a deep understanding of our SDKs and provides an immediate way to get support with your implementation—without necessarily needing to capture debug logs, etc.

You can ask the MCP server basic questions like, “My push notifications aren’t working. Can you help me troubleshoot the problem?”

Or you can ask more specific questions like, “Deep links in push notifications don’t work for customers in my Android app.” Or “I’m not receiving metrics for push notifications for iOS users.”

The tool will return detailed steps to help you find and troubleshoot problems.

Examine data in and data out traffic

Your integrations in Customer.io have Data in and Data out tabs showing you both the calls that come in from your SDK and the data we send out to your destination(s) respectively. You can examine these calls to help you debug issues.

If you have a problem, go to Integrations and check:

That your iOS integration is connected to your workspace. If you don’t connect your integration to your workspace, you won’t be able to send messages, etc. (Typically, it’s connected to your workspace by default.)
Your integration’s Data In tab to make sure that your app is sending the right data.
If data isn’t sent to your destination, or it appears incorrect in the destination, go to your outgoing integration’s Data Out tab. Check the calls there to make sure that we’re sending the right data from your SDK to the destination. This includes Customer.io: your workspace is one of the places you’ll send data from your app!

Check out Troubleshooting integrations for more help pinpointing issues in your integration.

Capture logs

Enable debug logging in your app: Everywhere you call CustomerIO.initialize(), enable the debug log level. This includes in the Notification Service Extension that you setup for rich push.

Note

You should not use debug mode in your production app. Remember to disable debug logging before you release your app to the App Store.
```
// During SDK initialization, enable debug logs:
CustomerIO.initialize(
withConfig: SDKConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")
   .logLevel(.debug)
   .build()
)
```
Open the Console app (already installed in MacOS). This is a built-in application you can use to view logs produced by the SDK. We recommend that you use Console instead of Xcode to view and capture logs from the SDK because Xcode may not show you all of the logs the SDK generates.
In Console, click Action > Include Info messages and Action > Include Debug messages. These settings ensure that you’ll see log messages from the SDK.
In Console, on the left, select the iOS device that runs your app with the Customer.io SDK. If you don’t see your device listed, plug in your iOS device into your Mac. Try to use a direct connection via the Apple cable; using a USB hub might prevent the device from showing up.

Then, click Start streaming. You will see hundreds or even thousands of logs printed to you. Most of these log messages are not relevant. In the next steps, we’ll filter your log to find relevant messages.
In the top right search bar, type “CIO” and press Enter.
Click the dropdown and select Category. You will now only see messages sent from the SDK.
In the top right, click Save to save this filter. The next time you open Console, just click that saved filter along the top of the screen to see Customer.io SDK logs.
Click any of the log entries on the screen (or Edit > Select All), CMD + C, then CMD + P into a text editor on your computer. Save the file as a .txt.
Send the file you just saved to our support team at win@customer.io. In your message, describe your problem and provide relevant information about:
- The version of the SDK you’re using.
- The type of problem you’ve encountered.
- An existing GitHub issue URL or existing support email so we know what these log files are in reference to.

NaN, infinite, or imaginary number values

Customer.io doesn’t handle invalid JSON values in your payloads, like NaN, infinite, or imaginary number values. If you send these values in identify, track, screen, or similar calls, we’ll drop them and record errors.

While we drop invalid values, we don’t drop the entire payload. The operation itself will still succeed. For example, if you send an identify call with two attributes, one of which is a NaN value, we’ll drop the NaN value, but the identify call succeeds with the other attribute.

Push notification issues

{{% include “integrations/sdk/push-troubleshoot-nse-target.md” %}}

Why don’t my messages play sounds?

Image display issues

Deep links only open in a browser

It sounds like you want to use universal links, links that go to your app if a person has your app installed and to your website if they don't. Universal links are a bit different than your average deep link and require a little bit of additional setup.

You can learn more about setting up universal links here. You can easily test universal links using your Notes app. Try adding a link to a note and tap it. If it drives you to your app, then you've set things up correctly.

If your links are opening Safari instead of your app, check this Apple document to troubleshoot.

Universal Link opens in browser instead of app

If you click on a push notification sent by Customer.io that contains a Universal Link deep link > click on the push notification > app opens for a moment > then the browser opens the URL, this could be a sign that something is wrong with your app’s Universal Link handling.

The Customer.io SDK sends a request to your app’s app to give your app an opportunity to handle the Universal Link. If your app does not handle the Universal Link, the SDK will open the link in the browser instead. Let’s walk through some troubleshooting steps to try and fix this behavior so the browser does not open.

In our deep links Universal Links guide, we show a function that is required to be added to your app: application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool. Add a print("Universal Links handle code called.") statement or Xcode breakpoint to verify that your code in this function does get called.

If you click on a push notification and you do not see this print statement or breakpoint hit, verify that the deep link URL is a valid https URL and you have followed all of the Apple documentation linked in our Universal Links guide.

If you do see your print statement or breakpoint hit, then your Universal Link URL is valid and is correctly attached to the push notification for the SDK to understand. Next, verify that your app returns true from the application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool function. If your app returns false, the SDK will open the Universal Link in the browser instead of the app.

Lastly, check if there is another SDK interfering with the Customer.io SDK. In some cases, customers have reported instances where Universal Links, despite being correctly configured within your app, may unexpectedly open in a web browser. This can occur due to interactions with third-party SDKs that perform method swizzling inside your app. To address this, consider reviewing the documentation of other SDKs integrated into your app and disabling swizzling as needed.