Square Market Item Embedding

September 05, 2013

Two months ago we launched Square Market, the online storefront for neighborhood businesses everywhere. Since launch, our item pages have allowed merchants and visitors alike to share their favorite items with their friends and followers on Twitter, Facebook and Pinterest. This feature allows merchants to reach more customers and helps buyers to find interesting items faster, wherever they are browsing.

While sites like Twitter and Facebook generate a ton of traffic and many people have strong followings there, we also know that people like to run their own websites, blogs and Tumblrs where they can go into more depth and focus on what's most important to them. We've heard from both merchants and Square Market visitors that they'd like to share items on these sites too. Today we're announcing a new item embedding feature to help make that happen.

What It Does

Our embedding script turns links like these:

Into full-featured item detail blocks like these:

Jamais deux sans trois pourpre orange from La Valise d'Alice on Square Market
Tokidoki Cactus Rocker from EDGE TOYS on Square Market
Hair of the Dog Bitters from DRAM Apothecary on Square Market
Spoon Small Colorblocked from Lydali on Square Market

Getting Started

All the HTML you need to embed a single item is included in the embed widget on Square Market item pages. To get started:

  1. Click the <> embed icon, found alongside our existing sharing icons:
  2. Copy and paste the HTML into your own site:
  3. There is no step 3! You can use the preview to see what your embedded item will look like in your page:

DIY

If you prefer to write the HTML yourself, simply:

  1. Add a link to the item you're interested in.
  2. Add class="sq-market-embed" to the link.
  3. Include the Square Market embed.js script in your page.

You only need to include the embed.js script once. With some knowledge of HTML, CSS and JavaScript it's possible to create a custom layout and even a full embedded storefront.

We've written several Square Market embedding examples that you're free to adapt for your own site. You can explore the samples on our square-market-embeds github project.

What Item Embedding Does

The code we give you to add an item to your page does two things: it includes a normal HTML link to your chosen item and it includes a script tag which replaces the link with an iframe containing the full content of the item.

For example, if you include a link to Jamais deux sans trois pourpre orange from La Valise d'Alice:

<a href="https://squareup.com/market/la-valise-dalice/jamais-deux-sans-trois-pourpre-orange"
   class="sq-embed-item">
  Jamais deux sans trois pourpre orange from La Valise d'Alice on Square Market
</a>

And the Square Market embed script:

<script src="https://cdn.sq-api.com/market/embed.js" id="sq-embed-js" charset="utf-8"></script>

You'll see the following content on your finished page:


Jamais deux sans trois pourpre orange from La Valise d'Alice on Square Market

Background

Here's my checklist for any new project:

  1. Make it work.
  2. Make it work right.
  3. Make it work fast.

To make it work, we had a few different options. Conventionally, when services offer an embedding feature they usually do it with an img, an iframe or a link and a script. We chose the latter. Behind the scenes we use an iframe to achieve the desired functionality, but we chose the script to keep things as flexible as possible.

For example, in future we might want to optimize the case where a page contains many items. With a script approach we'll be able to do that without asking people to change their existing embeds. With an iframe approach we'd be committing to serving those exact iframes forever (or risk breaking external sites). We want to add new features and respond to your feedback quickly; the script approach enables that most effectively.

To make it work right, we made sure that the script we ask you to add is small, served securely over SSL, and works across a wide range of devices and browsers. The embed uses a responsive design, so it adapts to the window size of the device you're using and is legible across mobile, tablet and desktop browsers.

Lastly, to make it work fast, we're serving the embed.js and images from a CDN. We also made a special template just for the embed that doesn't require all of our shopping-cart and checkout functionality, so it's served quickly and can be cached more aggressively.

The combined requirement of SSL and CDN means we're serving the script from a new domain, cdn.sq-api.com. You can count on us to keep this domain highly available so it won't affect the quality of your site.

Feedback

This is version 1.0 of the item embedding feature, we'd love to hear from you about how you're using it. If it doesn't meet your needs or live up to your expectations for content you include on your own site, please let us know that too. For specific help or bug reports, please contact our Help Center. For general feedback on the feature and anything outlined in this blog post, feel free to use the comments below this post.

Tom Carden
Data Visualization Engineer; Made in Britain. @RandomEtc

Comments

Get support help at squareup.com/support. We'll delete off-topic comments.