Add JSON-LD schema markup to donation receipt

[mathetos]

Feature Request

User Story

As a developer, I want the donation receipts to have relevant receipt data be accessible in various formats.

Details

Currently, it's difficult to grab the relevant donation receipt information from the donation receipt page. Each attribute of the receipt is in a raw table.

For example, if we're building out a Facebook Pixel add-on, we could easily grab this info from the JSON-LD schema markup.

Our Google Analytics addon, if I'm reading it correctly, has to manually output all the donation info onto the donation receipt page in order to trigger the GA event correctly.

If Give Core outputs the basic info in the schema format, then all of this gets a lot easier.

Possible Solution

Here's the spec for the DonateAction event from the Schema website: https://schema.org/DonateAction

Here's one example they provide, that would be easily done with our data:

<script type="application/ld+json">
  // John donated $10 to Steve.
{
  "@context": "http://schema.org",
  "@type": "DonateAction",
  "agent": {
    "@type": "Person",
    "name": "John"
  },
  "price": "10",
  "priceCurrency": "USD",
  "recipient": {
    "@type": "Person",
    "name": "Steve"
  }
}
</script>

Acceptance Criteria

• [ ] The schema markup is output on the Donation Success page
• [ ] The markup matches the fields that are available in the donation receipt table exactly
• [ ] Additional support for Recurring, Fee Recovery, Tributes should be considered as well.

[JasonTheAdams]

This is great, @mathetos, and certainly useful in this day-in-age. I'm curious how you imagine Recurring, Fee Recovery, and Tributes extending this? There doesn't seem to be recurrence or meta as part of the spec, and Fee Recovery would adjust the final amount to reflect the included the recovered fee.

So far the only scenario I don't have a clear answer for is the recipient attribute. We don't know whether the recipient is an Audience, Person, or Organization. We'd possibly need a setting for someone to provide a Recipient Type from a dropdown list and provide a name — we could default to the site name and "Organization", perhaps.

[mathetos]

Good points @JasonTheAdams

After a closer look, it seems that Recurring might be a lot harder to match to a specific schema. So, perhaps matching this with Schema is not as important as simply providing a way for other addons to access this information easily. So we could still provide the JSON-LD output, but in a much more GiveWP-centric manner.

<script type="application/ld+json">
  // John donated $10 to Steve.
{
  "@context": "http://schema.org",
  "@type": "DonateAction",
  "donor": {
      "type": "Person"
      "firstName": "John",
      "lastName": "Doe",
      "email": "johndoe@example.org",
   },
    "recipient": {
        "type": "Organization",
        "name": "San Diego Refugee Tutoring",
        "address": {
            "streetAddress": "1234 Street St",
            "city": "San Diego",
            "state": "CA",
            "zip": "92115"
         }
     },
    "donation": {
        "baseAmount": "25.00",
        "feeAmount": "0.75",
        "totalAmount": "25.75",
        "frequency": "once",
        "period": "none"
    },
    "addOns": {
        "mailChimp": {
                "optin": "true"
        },
        "tributes": {
                ...
        }
    }
}
</script>

Something like that would be extremely useful for social sharing addons, conversion tracking, and more.

[JasonTheAdams]

I don't understand what you're hoping to accomplish by breaking outside of the DonateAction spec? Consumers are going to assume the shape of the JSON-LD object. Extending it doesn't really do much unless a specific service is expecting it. Can you help me better understand your theorized use-case?

[mathetos]

From what I read -- and I could be wrong -- the JSON-LD spec is very flexible. The schema markup is not. I think we can use whatever key:phrase combinations we want with JSON-LD. Using Schema's structure is much more limiting.

The goal is this: When trying to grab data in the donation receipt page, plugins like Simple Social Share, Google Analytics, FB Pixel, all have to output the donation and donor meta hidden on the page somehow because it currently can't be grabbed easily. If we can't surface the data with Schema because of its limitations, then let's surface it some other way.

Also, in researching the FB Pixel addon, there are several other PIxel addons that offer integration with Woo and EDD already. But they don't with GiveWP, and I believe it's because of this same limitation, the data is not easily grabbable (or we just haven't popped up on their radar strong enough yet).

[mathetos]

With regard to data accessibility, Facebook provides a Chrome extension for detecting "pixels" on the site. It can automatically detect "microdata" under the following formats:

So in some ways it seems that just outputting this info -- properly formatted -- will do a large portion of the work for us.

I'm going to work on outputting some sort of JSON-LD output via the Facebook Pixel add-on I'm working on and then ideally I'll be able to report back with more detailed input.

[mathetos]

I've got the JSON-LD outputting in the FB Pixel addon now. And I'm pulling it in dynamically via JS as well. It's working as intended, and you can see that in the FB Pixel helper Chrome extension here:

The JSON-LD code I'm outputting is here: https://github.com/impress-org/givewp-facebook-pixel-tracking/commit/12e6b0c5fe1872e4ecde34a51efe6f027e25ffa1#diff-60c38bba8cedb558985a45f6148b6464R53-R68

[jonwaldstein]

@JasonTheAdams @mathetos did you ever come to a conclusion on this?

[mathetos]

Hey @jonwaldstein I think @JasonTheAdams never fully understood my use-case. I was trying to get the FB Pixel to consume our Donate Data easily. I think since then there's been other ways to make that info more accessible but I'm not familiar with how we did that. I thought this was an interesting and easy solution but I defer to Jason for sure.

[JasonTheAdams]

I recently learned that this can actually be done in the markup itself, which is pretty awesome!

https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemscope

I think the next time we make updates to the receipt page we add the appropriate markup to scope it to the DonationAction schema.

[github-actions[bot]]

This issue is stale because it has been open 45 days with no activity. Remove stale label or comment or this will be closed in 14 additional days.

[github-actions[bot]]

This issue was closed because it has been stalled for an additional 14 days with no activity.