pubdate	author
2016-10-24	Tyler Gaw

How We Use Groundwork Collections on Developer Center

In October 2016 we launched a design and content realign of The Developer Center. As part of that work, we created two areas that make use of the Collections resource of The Groundwork API.

Where we use Collections

Our first use of Collections is the API usage example curl request on the home page.

This is a low-level example of using The Groundwork API. Its purpose is to illustrate an API request using the fewest moving pieces as possible. Running the code in a terminal will create a new record in The Groundwork's¹ supporters collection.

( ¹ Note: The Groundwork Org uses The Groundwork in the same way as customers)

curl -X POST
  -u "pub-groundwork.developer-center--X4tVf0xy3jd3ccjy794prnkdx9qbPWUkW7TwSBKcvtMTGk_jJH4UIMNvcRrZki2VcrqERkAWMnrGQk66Ih7PGg:"
  -H "GW-Api-Version: 2016-08-04"
  -H "Content-Type: application/json"
  -d '{
    "schemaId": "7ac2dc55-d63c-44f3-9905-968a108dba95",
    "data": {
    "givenName": "Developer",
    "familyName": "Center",
    "email": "[email protected]"
    }  
  }' "https://api.thegroundwork.com/collections/supporters/records"

The code example from the home page

The second use of Collections is in the global footer of the site. We have a Developer Mailing List and a form in the footer to allow people to subscribe.

Supporters

When we use our own API, we make it a point to use it in the same way we expect our customers to. With that, the Collections demo and mailing list form use the default Supporters Collection and schema. This part of the API is public. Here's a live example of using Groundwork.JS to retrieve that schema; https://jsbin.com/mepezemaba/1/edit?html,js,output.

We use the supporters collection for the demo and list signup. The default schema is flexible enough to account for the fields we want to collect in each.

For the demo we illustrate collecting common fields; givenName, familyName, and email. For the list subscription we collect email and other metadata fields described later.

Data segmenting with Initiatives

We're using the same Collection for both the Supporters and Mailing List. That means all the data ends up in the same place. We want to segment the data between the two. This is where separate Initiatives come into play. When we export this data we are able to specify which Initiative we want. That allows us to export data for the Mailing List Initiative, which we use to populate a MailChimp list. In the future, we'll also be able to view the data in Admin based on similar segmentation.

For demos we use the Developer Center initiative and its single API key. We're not concerned about the cleanliness of the data coming in. We'll only use it as a quick gauge to see if the demos are being used. Our goal with them is not meaningful data collection.

The Developer Center Initiative in The Groundwork Admin

Our mailing list use is not like the demos. For it we'll use the data collected to add people to the mailing list. We need to treat this data with more care than the data from the demos. We do that by using the separate GW Developer Mailing List Initiative and API Key.

The GW Developer Mailing List Initiative in The Groundwork Admin

Further data collection

I mentioned earlier we collect metadata along with email for the mailing list subscriptions. It's important for us to know; where people are submitting the form, the context, and what drove them to the Developer Center.

Luckily, this is a well-paved path. The default supporters schema allows for all common utm fields. In the Developer Center JavaScript we parse url query parameters to check for utm fields. If they're found, we send them along with the subscription request. It's also helpful for us to know the page the user is on and where the form is on the page. For that we include metadata.formLocation and metadata.location. The former is hard-coded to 'footer' because that's the only place it can exist right now. The latter gets the value of window.location.

Here's an example of the JSON data when we retrieve a Mailing List Subscription record:

{
  "id": "dd147a06-1207-4eee-a6d0-61dfa7bd9de0",
  "created": "2016-10-22T04:58:23.109594Z",
  "modified": "2016-10-22T04:58:23.109636Z",
  "data": {
    "utmCampaign": "thisthingon",
    "email": "[email protected]",
    "utmSource": "tylersarticle",
    "metadata": {
      "env": "gw-prod",
      "location": {
        "origin": "https://developer.thegroundwork.com",
        "hostname": "developer.thegroundwork.com",
        "protocol": "https:",
        "port": "",
        "href": "https://developer.thegroundwork.com/?utm_source=tylersarticle&utm_campaign=thisthingon",
        "pathname": "/",
        "hash": "",
        "host": "developer.thegroundwork.com",
        "ancestorOrigins": {},
        "search": "?utm_source=tylersarticle&utm_campaign=thisthingon"
      },
      "formLocation": "footer"
    }
  },
  "schemaId": "7ac2dc55-d63c-44f3-9905-968a108dba95"
}

In the Dev Center JS for now we only allow a subset of available utm fields, but we can expand it as needed.

If you want to try this out, add custom utm params to any url in Dev Center. For example; visit https://developer.thegroundwork.com?utm_source=tylersarticle&utm_campaign=thisthingon and subscribe to the mailing list. The utm_source and utm_campaign are recorded with whatever values you put in. You can check this in the Network panel of the developer console in Chrome, Firefox, or Safari.

Going forward

This is us dipping our toe into Collections. If we only had the default schema we'd be able to cover a vast array of signup scenarios. We don't only have the default though. The Groundwork API allows for as many collections as we need with schemas in any shape desired.

tylergaw/how-we-use-collections.md