@giftme/partner-checkout

The @giftme/partner-checkout package enables Giftme partners to integrate a seamless gift card purchasing experience into their websites. This enhances the e-commerce capabilities of partners by allowing them to feature a custom-branded storefront for Giftme's diverse range of eGift cards.

Installation

Install the package with npm to include it in your project. This step is required before you can utilize the functionality provided by @giftme/partner-checkout.

npm install @giftme/partner-checkout

API Overview

Store Interface

The store interface contains methods for initializing and destroying the store modal. It ensures that the modal is correctly bound to the appropriate elements on the website for user interaction.

interface store {
    init: () => void; // Initializes the store and binds to elements.
    destroy: () => void; // Removes bindings and cleans up.
}

Widget Interface

The widget interface governs the display and behavior of a customizable button widget on the webpage, allowing users to interact and initiate the gift card purchasing process.

interface widget {
    attach: (config: WidgetConfig) => void; // Attaches a customizable 'Buy eGift cards' button to the page.
    destroy: () => void; // Removes the widget from the page when not needed.
    show: () => void; // Reveals the widget on the page.
    hide: () => void; // Conceals the widget from the user's view.
}

export interface WidgetConfig {
    url: string;
    position: Position;
    theme?: WidgetTheme;
    size?: WidgetSize;
}

export type WidgetTheme = 'primary' | 'secondary' | 'tertiary' | 'dark' | 'light' | '';
export type WidgetSize = 'xs' | 'sm' | 'base' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';

Positioning and Units

This section defines how to use CSS strings to position elements managed by the package, allowing for a responsive and adaptable layout.

export type PositionString = 'tr' | 'tl' | 'br' | 'bl'; // Corner positions shorthand: tr for top-right, tl for top-left, br for bottom-right, bl for bottom-left.
export type PositionObject = {
    top?: string; // Any valid CSS size value like '10px', '10rem', etc.
    left?: string;
    right?: string;
    bottom?: string;
    zIndex?: number;
};
export type Position = PositionString | PositionObject; // Allows for simple or detailed positioning.

Basic Usage

Widget Management

The widget management section guides you through adding the eGift card purchase button to your page, positioning it, and customizing its appearance and size.

import { widget } from '@giftme/partner-checkout';

widget.attach({
    url: 'https://<partner_id>shopgiftme.com',
    position: 'br', // Positioning options.
    theme: 'primary', // Theme options: 'primary', 'secondary', etc.
    size: 'xl', // Size options: 'xs', 'sm', 'lg', etc.
});

// Programatically show or hide the widget:
widget.show();
widget.hide();

// Remove the widget from the page when it's no longer required:
widget.destroy();

Widget Positioning and Customization Example

Examples showing how to position the eGift card widget using both shorthand positions and specific positioning objects, and how to apply themes and sizes.

// Customizing positioning, theme, and size
widget.attach({
    url: 'https://<partner_id>.shopgiftme.com',
    position: 'tr', // top-right
    theme: 'dark',
    size: 'md',
});

// Object positioning with theme and size
widget.attach({
    url: 'https://<partner_id>.shopgiftme.com',
    position: { bottom: '20px', right: '20px' },
    theme: 'light',
    size: '2xl',
});

Advance Usage

Store Initialization

Initializing the store sets up the necessary bindings to HTML elements with data-gpc-url, preparing them to open the store modal when interacted with.

import { store } from '@giftme/partner-checkout';

store.init();

HTML Element Example

Bind the store modal to an HTML element to provide users with direct access to the Giftme checkout interface.

<button type="button" data-gpc-url="https://<partner_id>.shopgiftme.com/store">Buy eGift Cards</button>

or

<a href="#" data-gpc-url="https://<partner_id>.shopgiftme.com/buy-gift-cards/<merchant>"> (Merchant) Gift Card </a>

Store Destruction

Destroying the store is crucial for cleaning up and ensuring that the modal bindings do not interfere with other JavaScript on the page when they are no longer needed.

import { store } from '@giftme/partner-checkout';

store.destroy();

Browser Usage

If your website does not use a build process with module bundlers, you can include the script directly in your HTML to use the package.

<script
    type="text/javascript"
    src="https://cdn.jsdelivr.net/npm/@giftme/[email protected]/dist/index.umd.js"
></script>

Example

<script type="text/javascript">
    // Assuming the global object `gpc` is exposed by the package
    window.gpc.store.init();

    // To destroy the instance when needed
    window.gpc.store.destroy();

    // Attaches widget to page
    window.gpc.widget.attach({
        url: 'https://<partner_id>.shopgiftme.com',
        position: 'br', // or an object like { bottom: '20px', right: '20px' }
    });
</script>

Support

Should you encounter any issues or require assistance, this section provides contact information for reaching out to the support team.