JavaScript SDK Banner

The JavaScript SDK can render a PPP discount banner similar to the standalone banner script, but with full programmatic control.

Usage

import { GoPayLocal } from '@gopaylocal/js';

const gpl = new GoPayLocal({ apiKey: 'gpl_pk_live_abc123' });
await gpl.init();

const banner = gpl.showBanner({
  position: 'bottom-right',
});

The showBanner() method returns a handle with a remove() method:

// Remove the banner programmatically
banner.remove();

If no discount applies (visitor is from a Tier 1 country, VPN detected, etc.), showBanner() returns a no-op handle:

const banner = gpl.showBanner();
banner.remove(); // Safe to call, does nothing

Options

Option	Type	Default	Description
position	'top' | 'bottom' | 'bottom-left' | 'bottom-right'	'bottom'	Banner position
backgroundColor	string	'#1a1a2e'	Background color
textColor	string	'#ffffff'	Text color
ctaColor	string	'#e94560'	CTA button color
ctaTextColor	string	'#ffffff'	CTA button text color
ctaText	string	'Copy Code'	CTA button label
messageTemplate	string	See below	Message with {{placeholders}}
showFlag	boolean	true	Show country flag emoji
showCloseBtn	boolean	true	Show close button
onClose	() => void	—	Called when banner is dismissed

Default Message Template

Hey! It looks like you're visiting from {{countryName}}.
We support Purchasing Power Parity! Use code {{code}} for {{discount}}% off.

Available Placeholders

Placeholder	Description	Example
{{discount}}	Discount percentage (number only)	30
{{code}}	Coupon code	PPP-INDIA-30
{{country}}	ISO country code	IN
{{countryName}}	Full country name	India
{{currencySymbol}}	Local currency symbol	₹
{{currencyCode}}	Local currency code	INR
{{flag}}	Country flag emoji	🇮🇳

You can use **bold text** in the template — it is rendered as <strong> elements.

Examples

Custom Colors

gpl.showBanner({
  position: 'top',
  backgroundColor: '#1e3a5f',
  textColor: '#ffffff',
  ctaColor: '#4fc3f7',
  ctaTextColor: '#1e3a5f',
});

Custom Message

gpl.showBanner({
  messageTemplate:
    '**{{countryName}} pricing!** Get {{discount}}% off with code **{{code}}**.',
  ctaText: 'Copy Discount Code',
});

With Close Callback

gpl.showBanner({
  position: 'bottom-right',
  onClose: () => {
    console.log('Banner dismissed');
    // Track in analytics
    analytics.track('ppp_banner_dismissed');
  },
});

Remove After Timeout

const banner = gpl.showBanner({ position: 'bottom' });

// Remove after 30 seconds
setTimeout(() => {
  banner.remove();
}, 30000);

Shadow DOM

Like the standalone banner script, the JavaScript SDK banner renders inside a Shadow DOM. This means:

• Your site’s CSS cannot affect the banner
• The banner’s CSS cannot leak into your site
• The banner is completely isolated from your page

CTA Behavior

When the user clicks the CTA button:

1. The coupon code is copied to the clipboard using navigator.clipboard.writeText()
2. If that fails, a fallback using document.execCommand('copy') is used
3. The button text changes to “Copied!” for 2 seconds
4. The text reverts to the original CTA text

Animations

The banner slides in with a 300ms ease-out animation:

Position	Animation
top	Slides down from above the viewport
bottom	Slides up from below the viewport
bottom-left	Slides in from the left
bottom-right	Slides in from the right

Note

Unlike the standalone banner script, the SDK banner does not send analytics events automatically. If you need analytics, use the banner script or send events manually via the Analytics API.