NAV
html

Introduction

This documentation explains how to include an existing 1o shop into your content.

What is a 1o shop?
Click here or visit our demo site to explore use cases.
How can 1o shops benefit your business?
Read more about 1o.
How can you set-up your own shop?
Reach out and we'll help you.

Shop URL

1o Shop URL is the basis to include the shop into your content:

Shop Example
ID af59a33d-e5c2-47fd-98a7-2151f6dda571
Description fashion-police-shirt
Format https://1o.io/checkouts/:id/:description#/option1=value1/option2=value2
Shop URL https://1o.io/checkouts/af59a33d-e5c2-47fd-98a7-2151f6dda571/fashion-police-shirt

Key points

  1. Opening in browser as a regular URL works fine.
  2. Using it in an iframe works. Purchase happens inside the iframe.
  3. Clicking on it can be intercepted by 1o.js script, which constructs an iframe and provides a nice on-site purchase experience.
  4. It's customizable with URL options.
  5. When hosted on site as an iframe it generates events you can listen to.

1o.js Script

<head>
  <!-- Place it in your head tag -->
  <script type="text/javascript" src="https://1o.io/js/1o.js"></script>
</head>
<body>
  <!-- Link intercepted by 1o.js -->
  <a href="https://1o.io/checkouts/:id">Open 1o Shop</a>

  <!-- Button opening a shop 1o.js -->
  <button onclick='OneO.openStorefront(":id", {mode: "popup"})'>
    Javascript works too.
  </button>

  <!-- Custom function opening a shop -->
  <div id="1o-shop-here">
    <button id="1o-shop-here" onclick='replaceMeWithOneO(self)'>
      Insert a 1o Shop here.
    </button>
  </div>

  <!-- Custom function opening a shop -->
  <script>
    function replaceMeWithOneO(toReplace) {
      OneO.openStorefront(
        ":id",
        { parentNode: toReplace.parentNode,
          insertBeforeNode: toReplace,
          preload: false,
          open: false,
          mode: "inline",
          width: 350,
          height: 200 }
      )
    }
  </script>

</body>

1o.js script tag facilitates integrating 1o shops into your content.

Open 1o Shop

Key Points

  1. Sets up 1o Shop iframes. Passes initial parameters via URL Options.
  2. Listens for events coming from 1o shop iframe via Post Message.
  3. Both mechanisms can be leverage to build integrations without the script.
  4. Provides a simple Javascript API to open 1o Shops programmatically.

URL Options

URL options are key=value pairs that customize 1o Shop's behaviour.\ They are appended to the URL after # (anchor), separated by / (forward slash).

https://1o.io/checkouts/:id/:description#/option1=value1/option2=value2

Options

Option Value Effects
showClose showClose=true Shows "close" button. Emits 1oStorefrontClose message when clicked.
placementId placementId=:string Analytics related events will include placementId: ":string".
sendImpression sendImpression=true (default) By default when a 1o shop renders an impression is counted. Customize it, if you thing this should not be the case.
mode mode=inline (default) When inserted into content as part of an article or blogpost.
mode=popup When full screen is available and you want to expand the iframe full screen. It grays out unused space and applies a nice border. On smart phones a dedicated experience is loaded.
mode=fullframe When appearing inside a nested limited iframe like an ad. Makes full use of space and does not behave like a pop-up window.
startScreen startScreen=PaymentMethods Sets a different starting page of the 1o shop. PaymentMethods value will move user straight into payment method selection. Use this when you gave user enough information for the purchase decision.
selectedVariant selectedVariant=:ID Bypasses default variant as the headline of the shop. Communicate with 1o representative to provide you with desired variant ID.
discountCode 'discountCode=shopify-discount' Auto applies a discount code to the checkout. Only supported for shops integrated with Shopify.

Options when 1o.js script is present

Option Value Effects
placementId placementId=:string Analytics related events will include placementId: ":string".
parentNode parentNode (dom el.) Shop is inserted into this Dom element element.
insertBeforeNode insertBeforeNode (dom el.) Shop is inserted before this Dom element.
mode mode=inline (default) When inserted into content as part of an article or blogpost.
mode=popup When full screen is available and you want to expand the iframe full screen. It grays out unused space and applies a nice border. On smart phones a dedicated experience is loaded.
mode=fullframe When appearing inside a limited iframe like an ad or layout designed by you. Makes full use of space and does not look like a pop-up (modal) window.
startScreen startScreen=PaymentMethods Sets a different starting page of the 1o shop. PaymentMethods value will move user straight into payment method selection. Use this when you gave user enough information for the purchase decision.
selectedVariant selectedVariant=:ID Bypasses default variant as the headline of the shop. Communicate with 1o representative to provide you with desired variant ID.
width width=:int (px) Set width in pixels. Applicable only when mode=inline.
height width=:int (px) Set height in pixels. Applicable only when mode=inline.

Events

<script>
  {
    "type": ":eventType",
    "event": ":eventName",
    "data": {}
  }
</script>

<script>
  window.addEventListener("message", event => {
    if (event.origin == 'https://1o.io' && event.data) {
      const oneoEvent = event.data
      if (oneoEvent.data.placementId == 'event-log-example'){
        const typeLog = document.getElementById('event-log-type')
        typeLog.append(document.createTextNode(oneoEvent.type))
        typeLog.append(document.createElement('BR'))

        const eventLog = document.getElementById('event-log-event')
        eventLog.append(document.createTextNode(oneoEvent.event))
        eventLog.append(document.createElement('BR'))
      }
    }
  })
</script>
1o Shop Event Type Event
Monitored 1o Shop

Lifecycle

<script>
  {
    "type": "OneoLifecycleEvent",
    "event": ":eventName",
    "data": {
      "storefrontId": ":string",
      "storefrontSlug": ":string",
      "placementId": ":string"
    }
  }
</script>
Event Description
1oCloseSplashScreen Loading screen closed.
1oStorefrontMounted 1o Shop is ready
1oStorefrontOrderFinished Purchase made, thank you screen rendered.
1oStorefrontClose Close button clicked.

Analytics

Plug this event into your own analytics system, to measure 1o's effectiveness.

<script>
  {
    "type": "OneoAnalyticsEvent",
    "event": ":eventName",
    "data": {
      "storefrontId": ":string",
      "storefrontSlug": ":string",
      "placementId": ":string",
      "testMode": ":boolean"
    }
  }
</script>
Event Description
impression Loading screen closed.
engaged 1o Shop is ready
transaction_success Purchase made, thank you screen rendered.

Send Events to 1o Shop

<script>
  iframeContainer.postMessage({
      type: "OneoEventTrigger",
      data: {
          eventToTrigger: {
              type: "OneoAnalyticsEvent",
              event: "impression"
          }
      }
  }, "*")
</script>

Send events into 1o Shop. Check the example on how to trigger an impression.

Use Cases

Website

<iframe src="https://1o.io/checkouts/966e7ba9-e36b-4733-ba86-732f30c40018"
        width="400"
        height="225"
        style="border: none">
</iframe>

Embed a one shop into your web-site's content.

Ad - shop from and ad

<iframe src="https://1o.io/checkouts/:id#/mode=fullframe/showClose=true"
        width="160"
        height="600"
        style="border: none">
</iframe>

1o shop can render inside an ad. This requires to take as much space as possible. Add mode=fullframe to fill all available space.

Buy Button

Sometimes you already know that buying without opening a new page is not possible. By making the shop small it reduces itself into a buy button, that opens in a new tab.

Order

Order model

{
    "paymentStatus": "paid",
    "customerName": "John Doe",
    "customerEmail": "[email protected]",
    "customerPhone": "+123456789",
    "billingName": "John Doe",
    "billingEmail": "[email protected]",
    "billingPhone": "+123456789",
    "billingAddressLine1": "Example address 132",
    "billingAddressLine2": "Apt. 4",
    "billingAddressCity": "Los Angeles",
    "billingAddressState": "CA",
    "billingAddressZip": "90002",
    "billingAddressCountry": "United States",
    "merchantOrganizationId": "3e90434d-9338-4356-8676-e7d99623a3ae",
    "shippingName": "John Doe",
    "shippingEmail": "[email protected]",
    "shippingPhone": "+123456789",
    "shippingAddressLine1": "Example address 132",
    "shippingAddressLine2": "Apt. 4",
    "shippingAddressCity": "Los Angeles",
    "shippingAddressZip": "90002",
    "shippingAddressCountry": "United States",
    "storefrontId": "af59a33d-e5c2-47fd-98a7-2151f6dda571",
    "fulfillmentStatus": "waiting",
    "totalPrice": 1200,
    "totalTax": 114,
    "totalShipping": 500,
    "total": 1814,
    "currency": "USD",
    "lineItems": [
        {
            "productId": "b6a3faa7-14a1-4629-b97e-9d7b62be8532",
            "variantId": "b06676ee-f10b-4d23-8462-f2dd0c8c6f41",
            "productMerchantData": "{\"RevOffersOrderMeta\":\"abcd-1234-efgh\"}",
            "variantMerchantData": "{}",
            "sku": "123456",
            "name": "Fashion Police Pink S",
            "imageUrl": "https://i.imgur.com/f6yn2DE.jpg",
            "details": "Fuchsia Pink • S",
            "quantity": 1,
            "price": 1200,
            "tax": 114,
            "total": 1314,
            "currency": "USD"
        }
    ],
    "transactions": [
        {
            "name": "Stripe charge",
            "total": 1814,
            "currency": "USD",
            "gatewayData": "{\"id\":\"pi_3JpvQHIj7KMjryuv2N0jTGuR\"}",
            "succeeded": true
        }
    ]
}
Variable Value Description
storefrontId String 1o internal ID of shop where order occurred
merchantOrganizationId String 1o internal ID of merchants organization
paymentStatus String(paid, pending, refunded or rejected) Status of the payment for the order.
customerName String Full name of the customer
customerEmail String Email of the customer
customerPhone String (Optional)Phone number of the customer
billingName String Billing persons Full Name
billingEmail String Billing persons Email
billingPhone String (Optional)Billing persons Phone
billingAddressLine1 String Billing persons Address Line 1
billingAddressLine2 String (Optional)Billing persons Address Line 2
billingAddressCity String Billing persons City
billingAddressState String Billing persons State
billingAddressZip String Billing persons Postal Code
billingAddressCountry String Billing persons Country
shippingName String Shipment recipient: Full Name
shippingEmail String Shipment recipient: Email
shippingPhone String (Optional)Shipment recipient: Phone
shippingAddressLine1 String Shipping addres: Address Line 1
shippingAddressLine2 String (Optional)Shipping addres: Address Line 2
shippingAddressCity String Shipping addres: City
shippingAddressState String Shipping addres: State
shippingAddressZip String Shipping addres: Postal Code
shippingAddressCountry String Shipping addres: Country
fulfillmentStatus String(fulfilled, waiting or cancelled) Status of the fulfillment
totalPrice Integer Total price of the products(quantity * products price) in cents
totalShipping Integer Total shipping cost of the order in cents
totalTax Integer Total charged tax in cents
total Integer Total amount charged
currency String(ISO 4217) Currency of the order
lineItems LineItem Information about ordered goods
transactions Transaction Information about all connected transactions

LineItem model

  {
      "productId": "b6a3faa7-14a1-4629-b97e-9d7b62be8532",
      "variantId": "b06676ee-f10b-4d23-8462-f2dd0c8c6f41",
      "productMerchantData": "{\"RevOffersOrderMeta\":\"abcd-1234-efgh\"}",
      "variantMerchantData": "{}",
      "sku": "123456",
      "name": "Fashion Police Pink S",
      "imageUrl": "https://i.imgur.com/f6yn2DE.jpg",
      "details": "Fuchsia Pink • S",
      "quantity": 1,
      "price": 1200,
      "tax": 114,
      "total": 1314,
      "currency": "USD"
  }
Variable Value Description
productId String 1o internal ID of shop where order occurred
variantId String 1o internal ID of merchants organization
productMerchantData String (Enabled upon request) (Optional) Stringified JSON. Data added on product import provided by merchant - intended for their unique data(eg. attribution system)
variantMerchantData String (Enabled upon request) (Optional) Stringified JSON. Data added on variant import provided by merchant - intended for their unique data(eg. attribution system)
sku String (Optional) SKU of the item
name String Name of the variant
imageUrl String URL to the main image of the item
details String Information about selected option
quantity Integer Amount of specific item ordered
price Integer Price of the item in cents
tax Integer Tax for the item in cents
total Integer Total cost of the item in cents
currency String(ISO 4217) Currency of prices

Transaction model

{
    "name": "Stripe charge",
    "total": 1814,
    "currency": "USD",
    "gatewayData": "{\"id\":\"pi_3JpvQHIj7KMjryuv2N0jTGuR\"}",
    "succeeded": true
}
Variable Value Description
name String Name of transaction and it's processor
total Integer Amount processed in transaction in cents
currency String Currency of the transaction
gatewayData String Stringified JSON with additional data. Will always posses id of the transaction inside the platform
succeeded Boolean True if transaction successfully completed
html