Quick Start

Learn how you can create metafields on the storefront.

Idea

The idea is pretty simple, FieldsRaven is exposing the Metafields API on the storefront through a Shopify app proxy so you may take full advantage of creating (or updating) metafields on the storefront.

As a developer you just need to write in Liquid, JS and FieldsRaven will handle what's under the hood to help you unlock the full potential of Shopify themes.

I built FieldsRaven to be a storefront metafields kit for Shopify.

Make sure on the storefront that FieldsRaven requests are to be sent by a logged-in customers, it adds an extra layer of security.

I installed the app, now what?

When FieldsRaven app is installed successfully on a Shopify store, there are a couple of steps you need to do to be able to start creating/updating metafields.

Step 1

Create a new Shopify theme snippet named raven-mac-gen.liquid, copy & paste the below code snippet into the new snippet in Shopify admin and don't forget to save! (Screen recording)

{%- liquid
  assign raven_api_secret = shop.metafields.fields_raven.api_secret
  assign raven_digest_string = raven_id | append: resource_id
  assign raven_mac = raven_digest_string | hmac_sha256: raven_api_secret
-%}
{
  raven_id: '{{ raven_id }}',
  resource_id: '{{ resource_id }}',
  raven_mac: '{{ raven_mac }}'
}

Step 2

Create a Raven in FieldsRaven app. (Screen recording)

Make your first request

Now that you created a Raven to carry messages and added the code snippet to a theme, it's time to create/update your first metafield.

The end-point that makes this possible is this end-point: /apps/raven/create_update_metafield which expects an object with the following attributes: raven_id, resource_id, value, raven_mac.

Create/update metafield.

PUT /apps/raven/create_metafield

All parameters are expected to be wrapped in an object

Request Body

Name	Type	Description
raven_id*	string
resource_id*	string	If a shop metafield is being created/updated the value must be shop
value*	string, number, json	metafield value
raven_mac*	string	Message auth code, generated by raven-mac-gen.liquid snippet

200 Metafield successfully queued

{
    "status": 200,
    "json": {
        "message": "Sit tight the raven is on it!"
    }
}

422: Unprocessable Entity Metafield error

{
    "status": 422,
    "json": {
        "message": "🚨🚨 OOOPS SOMETHING WENT WRONG 🚨🚨",
        "errors": {
            "resource_name": [
                "pagex is not a valid value_type"
            ]
        }
    }
}

All parameters are expected to be wrapped in an object

If you are creating a shop metafield resource_id value should be shop

FieldsRaven Storefront JS Kit

{% if customer %}
  <script type="text/javascript">
    window.addEventListener('FieldsRavenJSKitReady', (event) => {
      ravenSubmit = () => {
        const ravenObj = {%- render 'raven-mac-gen', resource_id: page.id, raven_id: 'WGv2c24' -%}
        const valueObj = { value: `Hello Raven! @ ${Date.now()}` };
        const requestParams = Object.assign({}, ravenObj, valueObj);
        const response = FieldsRaven.send(requestParams);
        response.then(res => {
          if (res.status === 200) {
            console.log('🎉', res.json)
          } else {
            console.error('😞', res)
          }
        })
        .catch(e => console.error(e));
      }
    });    
  </script>
  <!-- CTA -->
  <button id="fieldsraven-demo" onclick="ravenSubmit()">send the Raven!</button>
{% else %}
  <p><a href='/account/login'>Login</a> or <a href='/account/register'>create an account</a> to unlock this feature!</p>
{% endif %}

Vanilla JS

// Liquid
{% if customer %}
  <script type="text/javascript">
    window.addEventListener('FieldsRavenJSKitReady', (event) => {
      ravenSubmit = () => {
        const ravenObj = {%- render 'raven-mac-gen', resource_id: page.id, raven_id: 'WGv2c24' -%}
        const valueObj = { value: `Hello Raven! @ ${Date.now()}` };
        const requestParams = { raven: Object.assign({}, ravenObj, valueObj) };
        
        const response = fetch('/apps/raven/create_metafield', {
          method: 'PUT',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(requestParams)
        })

        response
          .then(res => res.json())
          .then(resJson => console.log('resJson: ', resJson))
      }
    });    
  </script>
  <!-- CTA -->
  <button id="fieldsraven-demo" onclick="ravenSubmit()">send the Raven!</button>
{% else %}
  <p><a href='/account/login'>Login</a> or <a href='/account/register'>create an account</a> to unlock this feature!</p>
{% endif %}

Storefront Kit

After installing the app, there should be a few App embeds in your Customize > Theme settings > App embeds.

For conveniance there is a Storefront Kit which contains few a JavaScript function to create/update metafields.

The Storefront Kit function will return a promise, when the promise is resolved it will return a JavaScript object that you may hook into to check on the status of the request and update the UI if you wish.

Example for a successful request

{
    "status": 200,
    "json": {
        "message": "Sit tight the raven is on it!"
    }
}

Example for a failed request

{
    "status": 422,
    "json": {
        "message": "🚨🚨 OOOPS SOMETHING WENT WRONG 🚨🚨",
        "errors": {
            "resource_name": [
                "pagex is not a valid value_type"
            ]
        }
    }
}

Pre-built theme examples

At the moment there are two App embeds examples to demo what might be built on top of FieldsRaven.

1. Birthday Popup: an example implementation for a customer birthday reward popup. (Screen recording). Learn more.

2. Sitemap and Search engines Hide/Show: an example implementation for sitemap/search engines to hide pages/templates from search results & sitemap (nofollow, noindex). (Screen recording). Learn more.

Each of those App embeds have settings, make sure to check them out.

Creating metafields on onload

If you're using FieldsRaven storefront kit, the kit triggers a FieldsRaven:ready event when it's loaded. So the following will do the trick.

window.addEventListener('FieldsRavenJSKitReady', (event) => {
  console.log('FieldsRaven storefront kit loaded!');
});

If you'd rather not use FieldsRaven Storefront Kit, then this should do the trick:

window.addEventListener('DOMContentLoaded', (event) => {
  console.log('DOM fully loaded and parsed');
});