New Prog Mixtape

    @loophq/onstore-sdk

    1.0.8 • Public • Published

    Loop Onstore SDK

    An SDK for easily getting started with the Loop Returns onstore API.

    Installing

    Add via CDN

    The easiest way to get started is to link it into your page via CDN and then use the global variable exposed to use the library.

    <script src="https://unpkg.com/@loophq/onstore-sdk@latest/dist/loop-onstore-sdk.js"></script>
    <script>
        LoopOnstore.init();
    </script>
    

    Module builds

    If you have a build process in place you can install via npm or yarn and import and use it as you need.

    npm i @loophq/onstore-sdk
    
    import { init } from '@loophq/onstore-sdk';
    
    init();
    

    Examples

    <script src="https://unpkg.com/@loophq/onstore-sdk@latest/dist/loop-onstore-sdk.js"></script>
    <script>
        LoopOnstore.init({
            key: '1234567890',
            attach: '#checkout-button'
        });
    </script>
    ...
    <!-- sidecart -->
    <button id="checkout-button">Check out</button>
    

    There's a single method that must be called for Loop Onstore to work correctly. You must run init() on any page you want this to be active on. We generally suggest putting this just above the </body> tag in your theme.liquid file.

    You'll need to pass in an options object that contains several things--an API key with the cart scope enabled, and any elements you want to attach to. An API key can be gotten by contacting support, and you'll need to find a selector for any checkout buttons you have, either on the cart page or in your sidecart if you use one.

    Styling

    Loop Onstore SDK injects a bar with the amount of credit available and a return to Loop Returns button. Default styling is applied, but you can further customize it with CSS as you see fit. To easily style it in browser, you can run LoopOnstore.testMode() in your browser console to see what elements we inject into the DOM, and style accordingly. If you just want to customize colors, you can just set these CSS custom properties and the changes will cascade through:

    .loop-onstore {
        --primary-color: black;
        --text-color: white;
        --button-background: white;
        --button-text: black;
    }
    

    You may also want to hide certain elements when a user is in the on-store flow. We also add the .loop-returns-activated class to the body of your page when on-store is active. You can use this to hide or adjust elements as you see fit. Some elements we recommend looking at are:

    Alternative payments or home try-on

    Your store may offer alternative payment options, instead of using Shopify checkout. Because these are not available on Loop On-Store, all alternative payment methods should be hidden. Common alternative payment methods include AfterPay, Google Pay & Paypal. These buttons typically appear on Side Carts and Cart pages. Similarly, if there are buttons for a Home Try-On program, those should also be removed.

    Help chat widgets

    It's not uncommon for your store to have a help chat widget at the bottom of their site. This will collide with the Loop On-Store credit indicator and should be adjusted when in the On-Store experience. You should use CSS to move the chat button up when in the returns experience to accommodate for the Loop on-store credit indicator.

    Mobile checkout

    Mobile bottom-bar add-to-cart buttons can cause trouble for the Loop On-Store experience and should be accounted for. An easy solution for this problem is using the .loop-returns-activated class and either move the elements around or simply adding display: none; to the items you don't want to show up.

    Popups and light boxes offering discount codes and special offers

    It’s a common paradigm now for Shops to show special offers through a pop up modal when a customer enters their site. Anything deviated from a customer adding product to there caught is distracting for returning customers, especially since these discounts will not apply to items bought using the Loop On-Store Experience. It is recommended that these be hidden.

    API

    Loop Onstore SDK exposes methods you can use to easily integrate with the Loop onstore API. If you're using the CDN link, you'll access these using the global variable LoopOnstore. If you're installing via package manager you can import the methods individually to use.

    init(options: object)

    Initializes the Loop onstore. You'll want to run this on every page load.

    LoopOnstore.init({
        key: '1234567890',
        attach: '.checkout-button'
    });
    

    Also dispatches the event Loop:Cart Updated on the document. This can be used for sidecarts to listen to and update if they don't automatically.

    Example:

    document.addEventListener('Loop:Cart Update', function (e) {
        console.log('The Cart has finished updating!')
    }, false);
    

    options

    Type: object

    key

    Type: string

    Required. This is your API key. You'll want to make sure that it has the cart scope.

    attach

    Type: string

    Required. This is a selector for any elements you want to attach to. The SDK uses document.querySelectorAll() under the hood and will attach to any elements that it finds. Generally we recommend that you attach to your checkout button, either on your cart page or in your sidecart if you use one of those instead.

    isActive

    Returns true if the on-store is active.

    if (LoopOnstore.isActive()) {
        // Do stuff
    }
    

    submit(variants?: array)

    LoopOnstore.submit(); // Pulls the Shopify cart
    LoopOnstore.submit([1234567890, 0987654321]); // Set the Loop cart to these variants
    

    Sync a list of variants to the Loop onstore API. If you pass in an array of variant ids, it will use that, otherwise it queries Shopify for the current cart and uses that to create a Loop cart. Once a Loop cart has been created, you'll be sent back to the Loop Returns app.

    variants

    Type: array

    Not required, if not set we query the Shopify cart directly. This should be an array of variant ids. The on-store API does not accept a quantity, so if you need more than one of the same variant, you'll need to add it to the array twice.

    backToLoop(token?: string)

    LoopOnstore.backToLoop(); // Sends you back without saving the user's cart.
    LoopOnstore.backToLoop('2e99758548972a8e8822ad47fa1017ff72f06f3ff6a016851f45c398732bc50c'); // Sends you back to loop with this cart.
    

    Sends you back to Loop. You must set the token you get from the Loop Onstore API when calling this if you want your user to have their cart when they return. The submit() method calls this automatically so generally you don't need to call this yourself.

    token

    Type: string

    Not required. Calling with a token sends you back with that cart, otherwise you get sent back without making changes to the users cart.

    testMode()

    This will send you into the onstore experience with fake data. You'll want to walk through the entire flow to make sure it works properly, but this is nice for testing that all of the functionality is attaching properly, and for styling the bar that we generate.

    debug()

    Toggle debug messages on and off, which will log to the console what's happening. Running the testMode method will enable this automatically. You should enable this if you're setting up an on-store integration or if something doesn't seem like it's working right.

    setKey(key: string)

    Sets your Loop onstore api key. This is required to communicate with the Loop Onstore API. Generally you'll want to do this via the init() method instead of directly here.

    key

    Type: string

    Required. This is your API key. You'll want to make sure that it has the cart scope.

    attach(selector: string)

    Pass this a css selector for your checkout button and the SDK will call the submit method automatically when a user is in the onstore flow. See examples to see how this works. Generally you'll want to do this via the init() method instead of directly here.

    selector

    Type: string

    Required. This is a selector for any elements you want to attach to. The SDK uses document.querySelectorAll() under the hood and will attach to any elements that it finds. Generally we recommend that you attach to your checkout button, either on your cart page or in your sidecart if you use one of those instead.

    Events

    In addition to the API, we also fire events at certain points in the flow. These events are fired on the document, meaning you can hook into them by adding an event listener to the document like so: document.addEventListener('Loop:Activated', () => {});.

    Activated

    Event: Loop:Activated

    This fires as we're activating the on-store experience. Note that this will only fire if the user is coming from the Loop app or is already in an on-store experience. You will not see this fire for normal users, only if on-store is active.

    Example

    document.addEventListener('Loop:Activated', () => {});
    

    Cart Update

    Event: Loop:Cart Update

    This fires every time we update the Shopify cart.

    Example

    document.addEventListener('Loop:Cart Update', () => {});
    

    Back To Loop

    Event: Loop:Back To Loop

    This fires directly before the user gets redirected back to the Loop app.

    Example

    document.addEventListener('Loop:Back To Loop', () => {});
    

    Versioning

    We use SemVer for versioning.

    Development

    Run npm i to install dependencies.

    Developing locally

    To develop locally, run npm run dev. This will spin up a webpack dev server with everything you need to get going.

    Building the library

    Run npm run build and the library will be built in production mode in /dist.

    License

    This project is licensed under the MIT License.

    Keywords

    none

    Install

    npm i @loophq/onstore-sdk@1.0.8

    Version

    1.0.8

    License

    MIT

    Unpacked Size

    318 kB

    Total Files

    9

    Last publish

    Collaborators

    • ericgpark
    • brandonfloop
    • phoebeloop
    • carlifay
    • stevejonesatloop
    • rissaloop
    • keithgulbroloop
    • katiebloop
    • eric-loop
    • bradleyloop
    • emilyrosenkranzloop
    • aaronjewell-loop
    • jeffhooton
    • chrisnetonline
    • alexrbrown