> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tappify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Symptom-first fixes for the most common Tappify SDK issues.

Find your symptom below. Each one links to the full fix.

| Symptom                                                                 | Jump to                                                                       |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| The pill never shows up                                                 | [Pill never appears](#pill-never-appears)                                     |
| Tapping an activation link does nothing                                 | [Activation link tap does nothing](#activation-link-tap-does-nothing)         |
| A toast says the app "couldn't connect to Tappify" after opening a link | [Activation link doesn't work](#activation-link-doesnt-work)                  |
| Comments or replies don't show up without force-quitting the app        | [Comments not syncing](#comments-not-syncing)                                 |
| SwiftUI screen names look generic or wrong in threads                   | [SwiftUI screen names look wrong](#swiftui-screen-names-look-wrong)           |
| Activation stopped working after adding another SDK                     | [Swizzling conflicts with another SDK](#swizzling-conflicts-with-another-sdk) |

## Pill never appears

There are five independent gates the SDK has to pass before the pill shows up. Check each
one:

| Possible cause                           | How to check                                                                                                                                                                  | Fix                                                                |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Gating mode is `off`**                 | Check your app's gating mode on the dashboard's Settings panel.                                                                                                               | [Gating modes](/sdk/gating-modes)                                  |
| **Build type doesn't match gating mode** | `internal_only` only allows TestFlight/dev builds; confirm which kind of build you're running.                                                                                | [Gating modes](/sdk/gating-modes#what-counts-as-an-internal-build) |
| **Device hasn't paired yet**             | Confirm this specific device has actually completed an activation exchange — installing the app isn't the same as pairing it.                                                 | [Activating devices](/sdk/activating-devices)                      |
| **Device was revoked**                   | Check the Devices list on the dashboard. Revocation takes effect on the device's next foreground, not instantly.                                                              | [Activating devices](/sdk/activating-devices#revoking-devices)     |
| **Crash shield tripped**                 | The SDK wraps every entry point in a crash-safety check; three consecutive internal failures disable it for the rest of that process launch. Force-quit and relaunch the app. | —                                                                  |

## Activation link tap does nothing

If your `AppDelegate`/`SceneDelegate` doesn't implement `application(_:open:options:)`,
`scene(_:openURLContexts:)`, or `scene(_:willConnectTo:options:)` at all, the SDK's
automatic swizzle has nothing to attach to and silently does nothing. This is the single
most common cause of "pairing just doesn't work."

**Fix:** call [`Tappify.handle(url:)`](/sdk/api-surface#tappify-handle-url) manually from
your own URL handling. It's safe to call unconditionally.

## Activation link doesn't work

If opening an activation link shows a "couldn't connect to Tappify" toast, the link is no
longer valid. By design, the toast is deliberately non-specific about why — the SDK shows
exactly one neutral message and never distinguishes the cause. The fix is always the same,
regardless of what actually happened to the link.

**Fix:** mint a fresh link from the dashboard's **Review on this device** dialog and try
again immediately.

Activation links are short-lived and single-use by design — see
[Activating devices](/sdk/activating-devices#the-60-second-link-lifetime) for why.

## Comments not syncing

If comments or replies don't appear without a manual force-quit and relaunch, this is
usually expected behavior rather than a bug:

* **On internal builds while offline:** the SDK holds a 24-hour cached-grace window and
  keeps showing the last-known state rather than going blank.
* **On live (App Store) builds:** there's no offline grace window — the overlay only shows
  what it can currently confirm with a live check.
* **In both cases:** there's no push channel. A change made from the dashboard, or by
  another reviewer, only shows up the next time the app checks in — cold launch or
  foreground. Background and re-foreground the app (or pull-to-refresh the thread list) to
  force a refresh.

See [Gating modes](/sdk/gating-modes#how-fast-a-change-takes-effect) for the underlying
mechanics.

## SwiftUI screen names look wrong

The automatic screen-name capture names screens after their hosting view controller class,
which is often unhelpful for composed SwiftUI views — you'll see something generic instead
of a name that matches what the screen actually is.

**Fix:** add `.tappifyScreen("YourScreenName")` to the view, or call
`Tappify.tagScreen("...")` directly. See [Screen names](/sdk/screen-names).

## Swizzling conflicts with another SDK

If activation links stop working after adding another SDK that also swizzles URL-handling
methods, the two swizzles are conflicting — this kind of ordering conflict is hard to debug
by design, and not worth trying to.

**Fix:** sidestep it entirely. Call
[`Tappify.handle(url:)`](/sdk/api-surface#tappify-handle-url) manually from your own URL
handling, rather than relying on both SDKs' swizzles to cooperate.