Easy Smart App Banner

An Easy Smart App Banner for promoting mobile app installs based on the Safari Apple Experience.

Note

This isn't for everyone. Most people should probably prefer the PWA approach. However, if you need a 'simple' banner that redirects to a native mobile app then keep reading.

For Safari support see Safari Support. For specific details on iOS and Safari, read here. Likewise for Android see here.

Features

• Typescript support
• Standalone/Frameworkless
• Small! 14.72 kB │ gzip: 4.36 kB │ map: 52.03 kB
• Platform specific
  • custom banner for iOS (non-Safari) and Android user agents
  • Safari specific config See Safari Support
• Option, use SCSS/Sass variables to configure the banner as needed
• Cookie-based dismissal, dismiss once per browser

---

Install

npm i -S @easy-smart-app-banner/core

Configuration

smart-app-banner/src/models.ts

Lines 1 to 110 in a3b0ec2

	export type SupportedPlatForm = 'android' | 'ios' | 'safari';
	export type SmartBannerOptions = {
	title: string;
	author: string;
	/**
	* The main asset to show. This should is expected to be a URL that resolves an image.
	* This can be overriden on a per-platform basis as needed.
	*/
	icon?: string;
	/**
	* Enabled platforms. If a platform is enabled here it must be configured.
	*
	* If 'safari' is included, then the native Safari banner will be enabled and require additional configuration.
	* Ensure that the appleAppId and (optionally) the appleAppArgumentUrl.
	*
	* @see https://developer.apple.com/documentation/webkit/promoting-apps-with-smart-app-banners
	* @default ['android', 'ios']
	*/
	platforms: SupportedPlatForm[];
	/**
	* The price tagline of the app, this can be any string you prefer.
	* This can be overriden on a per-platform basis as needed. If not provided, then the platform
	* specific options will be preferred.
	*
	* @default undefined (prefer platform specific by default)
	*/
	price?: string;
	/**
	* View button label. This can be overriden on a per-platform basis as needed.
	* @default View
	*/
	buttonLabel?: string;
	/**
	* Enable verbose logging. Disabled by default.
	*
	* @default false
	*/
	verbose: boolean;
	// --------------------------------------------
	// Android Platform Options
	/**
	* The Google Play Store URL.
	*
	* @example https://play-store-application-url
	*/
	googlePlayStoreUrl?: string;
	/**
	* Android specific button label. If not specified, falls back to buttonLabel.
	*/
	androidButtonLabel?: string;
	/**
	* Android specific icon. This should is expected to be a URL that resolves an image.
	*/
	androidIcon?: string;
	/**
	* Android specific price tagline.
	* @default GET - On the Google Play Store
	*/
	androidPrice?: string;
	// --------------------------------------------
	// Apple Platform Options
	/**
	* The Apple app store URL.
	* @example https://app-store-application-url
	*/
	appStoreUrl?: string;
	/**
	* Sets the Apple app store ID. This IS required if enableSafariSupport is true
	*
	* @see https://developer.apple.com/documentation/webkit/promoting-apps-with-smart-app-banners
	*/
	appleAppId?: string;
	/**
	* Sets the argument URL parsed to Safari browsers.
	*
	* @see https://developer.apple.com/documentation/webkit/promoting-apps-with-smart-app-banners
	*/
	appleAppArgumentUrl?: string;
	/**
	* Apple specific button label. If not specified, falls back to buttonLabel.
	*/
	appleButtonLabel?: string;
	/**
	* Apple specific icon. This should is expected to be a URL that resolves an image.
	*/
	appleIcon?: string;
	/**
	* Apple specific price tagline.
	* @default GET - On the App Store
	*/
	applePrice?: string;
	};

Safari Support

This libary currently excludes Safari, as it is not possible to support Safari via a library/plugin/etc. Support for the native Safari smart app banner MUST be provided via static meta tags in your site directly. Safari currently only supports parsing this metadata immediately on page load and will not parse any metadata added after this point. If you want to natively include the Safari banner, then read on here.

Advanced Usage

Platform Specific Overrides

Several options have platform specific overrides. These take precedence over any equivalent option when running on the relevant platform.

For specific details on iOS and Safari specifically, read here. For Android see here.

Icon

A single icon is typical, but specific ones can be configured.

{
    icon: '/assets/my-icon.jpeg',
    androidIcon: null,
    appleIcon: null,
}

Price

The price tagline defaults to FREE with platform specific defaults for both Android and iOS platforms.

{
    price: 'FREE',
    androidPrice: 'FREE - On the Google Play Store',
    applePrice: 'GET - On the App Store'
}

Call to Action Button Label

{
    buttonLabel: 'View',
    androidButtonLabel: null,
    appleButtonLabel: null
}

SCSS/Sass Variables

Styles can be overriden using the provided SCSS/Sass variables.

smart-app-banner/src/styles/_vars.scss

Lines 1 to 8 in 3b9011f

	// https://sass-lang.com/documentation/variables/
	$background-color: #f3f3f3 !default;
	$font-color: #000 !default;
	$font: Helvetica, sans, sans-serif !default;
	$view-button-color: #1474fc !default;
	$close-button-color: #716f6f !default;
	$close-size: 16px !default;
	$icon-size: 64px !default;

You can provide these styles as needed by using the .scss files instead,

@use 'smart-app-banner/dist/variables' as *;

// overwrite as needed
$background-color: #000;

Platform Specific Plugins

Looking for a platform that isn't here? Propose a PR to add it!

• Vue 3 Plugin

Testing if your User Agent (UA) String is Valid

UA strings are a dime a dozen, that's why in verbose mode (see Configuration), the platform parsing utility is exposed to the window object for easy testing. In your browser console,

const myUa = window.navigator.userAgent;
getCurrentPlatform(myUa)

This is especially useful when debugging known UA strings that may not be supported. If you think a particular UA should be supported, open a pull request!

Development

To get started, pull the repo and run a build as well as the tests.

don't forget to run npm i!

npm run build
npm run test

You can checkout the rest of the commands in the package.json.

The next step would be to boot a demo project. Checkout the Vue demo here.

Publish a Release

1. Checkout a new branch release/major.minor.patch
2. Create the new version using npm version major|minor|patch
3. Update the README's as needed (bump the size note)
4. Publish the branch

Having merged the PR for that branch, use GitHub and the configured GitHub Action to generate a release with a matching tag for the newly created version.

Licence

MIT License © 2025-PRESENT Albert Ferguson