How do I make Piano Identity Management templates render correctly in mobile browsers, native apps, and the iOS/Android SDK?

Where to make these changes

Almost every CSS-based fix below goes in the Piano ID Layout template, accessed via Designer → Templates → Piano ID → Layout → CSS tab in the Composer dashboard. Changes there propagate to all Identity Management screens (login, register, password reset, email confirmation, custom forms, etc.) — there is no per-template CSS override at this level, so test broadly when you change it.

Native-app implementation overview

For native apps, Identity Management templates are loaded through the Piano Mobile SDK (iOS and Android). Implementation reference:

• Identity Management templates documentation: the same templates configured at Manage → Templates → Piano ID are used.

• For Android, see the Piano SDK for Android GitHub repository (the SDK exposes a Composer-based call to show templates).

• For iOS, see the Piano iOS SDK guide for showing templates.

Key design considerations:

• Templates are responsive by default. The Piano ID Layout adapts to screen size and orientation. If the native app design requires further changes, use custom CSS and media queries in the Piano ID Layout.

• Native vs. web styling: if you want a different look in the native app than on the web, wrap the app content in a WebView and apply distinct CSS — the WebView owns the rendering box and the publisher controls its sizing.

• showIfStage is not available in the iOS/Android SDKs. Plan branching with other directives or with template variants assigned to different applications.

Angular directives for native vs. OAuth contexts

The Identity Management templates support a set of directives to conditionally render content based on context.

• *showIfMobileSdk — shows the element only when the template is running inside the Piano Mobile SDK.

• *hideIfMobileSdk — hides the element when the template is running inside the Mobile SDK. Requires the * (asterisk) prefix to function. It is implemented as an Angular structural directive, and without the * the conditional is silently ignored.

• *showIfOauth — shows the element only when the template is running on an OAuth authorization page.

When combining these, do not put two structural directives on the same element. Nest instead:

<div *showIfOauth>
  <div *hideIfMobileSdk>
    <!-- Content shown on OAuth page in web, hidden inside Mobile SDK -->
  </div>
</div>

The asterisk on *hideIfMobileSdk is a frequent gotcha — the directive was not initially documented as a structural directive, but it must be used as one.

Full-screen Identity Management forms on small screens

To make Identity Management login/register forms cover the full viewport on phones, add a media query to the Piano ID Layout CSS. Two recipes apply:

Strict full-screen with no backdrop or shadow (also works for email-verification system templates):

@media only screen and (max-width: 500px) {
  .tp-iframe-wrapper.tp-active {
    position: fixed !important;
    top: 0 !important;
    left: 0 !important;
    right: 0 !important;
    bottom: 0 !important;
    width: 100% !important;
    height: 100% !important;
    margin: 0 !important;
    box-shadow: none !important;
  }
  [id*="piano-id"] {
    width: 100% !important;
    height: 100% !important;
  }
}

Lighter-touch full-screen (no backdrop change, just sizing):

@media only screen and (max-width: 500px) {
  .tp-iframe-wrapper.tp-active {
    margin: unset !important;
    width: 100% !important;
    height: 100% !important;
  }
  [id*="piano-id"] {
    width: 100% !important;
    height: 100% !important;
  }
}

Both rules affect ALL Identity Management templates served at that breakpoint (login, register, email confirmation, etc.). If you need to reposition the close button after going full-screen, add further CSS for the close-button selector. Test in sandbox before publishing.

Customizing the SDK login modal on iPads

iPads do not always match phone breakpoints. To target most iPad sizes specifically and increase the modal height (e.g. to 800px):

@media only screen and (max-device-width: 1190px) {
  .tp-iframe-wrapper.tp-active { height: 800px !important; }
  [id*="piano-id"] { height: 800px !important; }
}

Notes:

• max-device-width: 1190px catches most iPads — adjust if you have a specific device list.

• Changes here apply to both the app and the web version of the site because the Piano ID Layout is shared. Test on both.

• Clear the device cache to see the change.

iFrame height issues on older iOS devices (Safari 12/13)

On older iOS Safari (iOS 12–13) there is a known WebKit bug: viewport height (vh) units and DOM measurements inside nested iframes return values smaller than the actual viewport. The Piano login iframe ends up occupying only about two-thirds of the available space, and because the Piano wrapper defaults to overflow:hidden, the user cannot scroll to elements at the bottom (e.g. the Register button).

The workaround is to hard-code a minimum/fixed height in the Piano ID Layout CSS, scoped to the affected devices:

/* Older iPhones (e.g. iPhone 11 in portrait, around 414px wide) */
@media only screen and (max-device-width: 430px) {
  .tp-iframe-wrapper.tp-active,
  iframe[src*="piano-id"] {
    height: 750px !important;
    min-height: 750px !important;
  }
}

/* iPad mini (7.9" — width ≤ 768px) */
@media only screen and (min-device-width: 431px) and (max-device-width: 1024px) {
  .tp-iframe-wrapper.tp-active,
  iframe[src*="piano-id"] {
    height: 800px !important;
    min-height: 800px !important;
  }
}

Using the .tp-iframe-wrapper.tp-active selector with !important blocks Piano's JavaScript from re-shrinking the element after render.

Validation:

• Save the changes in a sandbox copy of the Piano ID Layout.

• Clear the device cache and reload.

• Confirm the modal renders tall enough that the entire login form (including the Registration button) is visible and reachable.

• Test both portrait and landscape; adjust pixel values as needed.

• Ensure no site-level styles (max-height, flex, transforms) interfere.

Generic iframe-too-small fix

If the iframe renders too short on desktop or specific browsers (sometimes seen sporadically in Chrome on desktop), you can set a baseline body height inside the template CSS:

body { height: 928px !important; }

Replace 928px with the height you need. This applies to all Identity Management templates, not just one form.

Preventing modal/ad overlap on mobile

On mobile, sticky bottom ads can overlap the Piano modal, blocking the user from completing checkout or seeing terms. Two approaches:

Cap modal height and add scroll:

.piano-id-container {
  max-height: 400px;
  overflow: scroll;
}

The exact height should be tuned to leave space for the ad. Adjust the piano-id-container selector if your implementation uses a different wrapper.

Test locally before going live: make the change in your browser's DevTools console and refresh — your session will reflect the change without affecting other users.

Caveats:

• These changes apply site-wide; you cannot restrict them to specific URLs or articles via the Piano ID Layout alone.

• Test across iOS Safari, Android Chrome, and any in-app browsers in scope.

Responsive forms on mobile devices (progressive registration)

When you build progressive-registration forms or Custom Forms intended to render in mobile browsers, the iframe wrapping the form can receive width and height as inline styles set by JavaScript. On some Android tablets in Chrome and on iOS in Safari, widths can range wildly (350px down to 30px), leaving the form unusable.

To address this:

• Use media queries that respond to the screen size, not the iframe size. Querying iframe dimensions inside the form leads to inconsistent behavior because the iframe's reported size may not match the device.

• Update the relevant template's CSS in Manage → Templates → Piano ID.

• If your integration dynamically sets iframe container dimensions in JavaScript, review and tighten that logic so it produces consistent values across devices and orientations.

• Provide staging credentials when reporting/triaging — testing must run end-to-end on the device to confirm fixes.

Integrating Identity Management templates in native apps — quick reference

Limitations recap

• showIfStage does not work in the iOS/Android SDKs.

• All CSS changes in the Piano ID Layout are global to every Identity Management template — test full-screen, modal, and email-confirmation flows after each change.

• Changes can take a CDN refresh; clear browser/device cache when validating.

Last updated: July 03, 2026