Most eSIM products treat delivery as an afterthought: the order succeeds, an email goes out with a QR code, done. Then the support tickets start. "The QR code won't scan." "It says the code is no longer valid." "I installed it but nothing happens."
How the eSIM profile gets from your backend onto the customer's phone is a product decision, not a transport detail. You have roughly three options: a QR code, a one-tap installation link, or an install that happens inside your own native app. Each removes some failure modes and introduces others. This post walks through all three, what to log for each, and how to choose.
What is actually being delivered
Whatever the path, the payload is the same: an activation code that tells the phone's eSIM manager (the LPA, or Local Profile Assistant) where to download the profile and which profile to ask for. In the common format it looks like this:
LPA:1$smdp.example.com$MATCHING-ID-123
The middle part is the SM-DP+ address, the server that holds the profile. The last part is the matching ID that identifies this specific order. Some providers also require a confirmation code, which the customer has to type in separately.
The QR code, the link and the in-app call are just three different envelopes for that string. What differs is who has to handle the envelope, on which device, and what happens when it goes wrong.
Path 1: the QR code
The QR code is the universal default. Every eSIM-capable phone can scan one from its settings, and you don't need an app. That's why almost everyone starts here.
Its failure modes are mostly physical and timing-related:
- The customer can't scan the code with the phone being set up. The QR arrives by email, the customer opens the email on that same phone, and now there's nothing to point the camera at. Some will print it, some will find a second screen, many will contact support. Always show the activation code as copyable text next to the QR, and tell people up front that they need a second screen or the manual code.
- The code has already been used. Many SM-DP+ servers treat an activation code as single-use. If the customer scanned it once to "test" it, deleted the profile, or installed it on the wrong phone, the second scan fails. The exact behaviour depends on your provider, so find out whether a used profile can be released and re-issued, and how long that takes.
- The code was installed too early. Some plans start their validity on install rather than on first network attach. A customer who installs a week before the trip may lose days. Your copy needs to say clearly when to install.
QR codes are also easy to forward. That's fine for a family member's phone, and a problem when a customer shares a screenshot publicly while asking for help.
Path 2: the one-tap installation link
A one-tap link wraps the same activation code in a URL that the operating system recognises and hands to the eSIM setup flow. Since iOS 17.4, Apple supports a universal link format that starts the eSIM installation directly when it's opened on an iPhone. That removes the "scan the screen you're holding" problem completely: the customer taps the link on the phone being set up.
On Android, support for link-based installation varies by OS version and manufacturer, so check current documentation and test on the devices your customers actually use before you make it the main path. A QR or manual code fallback is still needed.
The new failure mode is the in-app browser. If the link is opened inside Gmail's, Instagram's or another app's embedded browser rather than Safari, the hand-off to the system eSIM flow often doesn't happen. The customer sees a blank page or a download prompt, and assumes the eSIM is broken. Practical mitigations:
- Send the link to a page you control first, detect whether it's running in an embedded web view, and show an "Open in Safari" instruction if so.
- Keep the QR and the manual code on that same page as fallbacks.
- Don't wrap the install link in click-tracking redirects that may break the universal link behaviour. Track the visit on your landing page instead.
The single-use problem doesn't go away either. A link that has been tapped once is a code that has been redeemed once.
Path 3: install inside your own app
If you have a native app, you can trigger the installation from inside it. The customer taps "Install eSIM", confirms in a system dialog, and never sees a QR code or a link. This removes both earlier failure modes: there's nothing to scan and nothing to open in the wrong browser.
The catch is access. On iOS, programmatic eSIM installation requires an entitlement that Apple grants to carriers and approved partners. On Android, an app generally needs carrier privileges for the profile to manage it through the platform eSIM APIs. Neither is something you switch on in a weekend, so ask your connectivity provider early what's possible for your brand and plan for it.
The trade-off is ownership. When the install happens in your app, every remaining problem (an incompatible or carrier-locked phone, a failed download, the line not being enabled, data roaming switched off) lands in your support queue, with your brand on it. That's a good thing if you're prepared for it: you can guide the customer through enabling the line and turning on roaming in the same flow. It's a bad thing if your support team expects only billing questions.
What to log, whatever the path
Most "my eSIM doesn't work" tickets are slow because nobody can tell where in the process the customer got stuck. Log enough to answer that in one lookup:
- Order ID and ICCID, linked to each other and to the customer.
- Delivery path and timestamp: QR emailed, link sent, or in-app install started.
- Issued vs redeemed: whether the activation code has been downloaded by a device, and when. Your provider's API or the SM-DP+ status usually exposes this.
- Profile notifications: the GSMA consumer eSIM spec defines notifications that devices send back to the SM-DP+ on install, enable, disable and delete. If your provider forwards them, store them. "Installed but never enabled" is a very different ticket from "never downloaded".
- Landing page events for links: page opened, embedded browser detected, install tapped, fallback shown.
- First network attach or first usage, if available, so you know the line actually worked abroad.
With these fields, support can answer "where are you stuck?" before asking the customer anything.
How to choose
A simple way to decide:
- No native app (webshop or email-only flow): lead with the one-tap link on a landing page you control, with the QR and manual code below it. Detect embedded browsers. Explain when to install.
- Native app, no install entitlement yet: open your own install landing page from the app in the system browser (not a web view), so the link hands off correctly. Show order status in the app.
- Native app with install access: make in-app install the default, keep the link and QR as fallbacks for a second device, and invest in in-app troubleshooting for enabling the line and data roaming.
Whichever you choose, measure it. Track tickets by delivery path and failure stage (never downloaded, downloaded but not enabled, enabled but no data). If one path generates most of the "code already used" or "nothing happens" tickets, that's where the next fix goes.
About One-eSIM
I work on One-eSIM, a B2B platform that lets travel, fintech and telecom brands launch their own branded eSIM through a white-label webshop or an API embed, with a management portal and support tooling behind it. If you're deciding how your customers should receive and install their eSIM, you can see how the pieces fit on our partner solutions page or at 1-esim.com.
Top comments (0)