Allow Open Graph image URL to be customised

[36degrees]

We previously told users that if they needed to override the OpenGraph image they should add their own meta tag to the head block and that this would override the one in the template (based on the spec). Some users have found that this isn’t reliable or can result in multiple images being displayed – and it’s a waste of bytes to include a redundant meta tag.

Instead, allow the OpenGraph image URL in the template to be set using a new opengraphImageUrl Nunjucks option.

If no opengraphImageUrl is provided, keep the existing behaviour that uses assetUrl as a prefix for a non-customisable path of images/govuk-opengraph-image.png.

However, when neither opengraphImageUrl or assetUrl are passed, no longer fall back to using the assetPath option. OpenGraph image URLs must be absolute and using the assetPath only gives us a relative URL, so we should just omit the OpenGraph image tag in these cases.

This is a change in behaviour, as previously an og:image meta tag would always be included, but it only be valid if assetUrl had been set.

Fixes #1920.

[36degrees]

This will need a corresponding change to the page template guidance in the Design System, to add opengraphImageUrl to the table of options and to update the description for assetUrl.

[36degrees]

Raised a PR to update the guidance for the page template: alphagov/govuk-design-system#2228

[querkmachine]

Looks good from a tech POV.

Would the change to requiring an explicit assetUrl be considered a breaking change?

Are there situations where a team may have placed their OpenGraph image at /assets/images/govuk-opengraph-image.png explicitly because that was the default location?
Presumably they would now need to add {% set assetUrl = "/assets" %} somewhere.

Relatively minor as breaking changes go, and probably not a blocker to putting this in a feature release unless we want to be strict about it, but something to note.

[36degrees]

Would the change to requiring an explicit assetUrl be considered a breaking change?

I believe this change should only impact cases where assetUrl is not set, and should only result in invalid meta tags from being included. As such, I think we should treat this as a non-breaking change.

The only exception that I can think of would be if a user has 'incorrectly' set assetPath to an absolute URL – see the bottom example.

Are there situations where a team may have placed their OpenGraph image at /assets/images/govuk-opengraph-image.png explicitly because that was the default location?
Presumably they would now need to add {% set assetUrl = "/assets" %} somewhere.

If that was the case, the current meta tag would be invalid according to the spec as it would only be a relative URL. Of course, it might be that some social sharing sites 'do the work' to try and resolve it to an absolute URL anyway – if so this would break that. But in this instance I think we're better off following the spec and only including the meta tag if we know the absolute URL.

Therefore, in order to correctly implement the Open Graph image the team would now need to either set assetUrl or the new opengraphImageUrl variable.

✅ Asset URL ✅ User-provided meta tag in head block

{% set assetUrl = "https://example.com/assets/" %}

{% block head %}
<meta property="og:image" content="https://another-example.com/whatever/images/govuk-opengraph-image.png">
{% endblock %}

Before

Two meta tags would be included:

• <meta property="og:image" content="https://example.com/assets/images/govuk-opengraph-image.png">
• <meta property="og:image" content="https://another-example.com/whatever/images/govuk-opengraph-image.png">

After

No change. Two meta tags would be included:

• <meta property="og:image" content="https://example.com/assets/images/govuk-opengraph-image.png">
• <meta property="og:image" content="https://another-example.com/whatever/images/govuk-opengraph-image.png">

✅ Asset URL ❌ User-provided meta tag in head block

{% set assetUrl = "https://example.com/assets/" %}

Before

One meta tag would be included:

• <meta property="og:image" content="https://example.com/assets/images/govuk-opengraph-image.png">

After

No change. One meta tag would be included:

• <meta property="og:image" content="https://example.com/assets/images/govuk-opengraph-image.png">

❌ Asset URL ✅ User-provided meta tag in head block

{% block head %}
<meta property="og:image" content="https://another-example.com/whatever/images/govuk-opengraph-image.png">
{% endblock %}

Before

Two meta tags would be included:

• <meta property="og:image" content="/assets/images/govuk-opengraph-image.png"> – INVALID as the URL is not absolute
• <meta property="og:image" content="https://another-example.com/whatever/images/govuk-opengraph-image.png">

After

One meta tag would be included:

• <meta property="og:image" content="https://another-example.com/whatever/images/govuk-opengraph-image.png">

❌ Asset URL ❌ User-provided meta tag in head block

{# Nothing set #}

Before

One meta tag would be included:

• <meta property="og:image" content="/assets/images/govuk-opengraph-image.png"> – INVALID as the URL is not absolute

After

No meta tags would be included.

❌ Asset URL ❌ User-provided meta tag in head block ✅ Asset Path

{% set assetPath = "/my-custom-path" %}

Before

One meta tag would be included:

• <meta property="og:image" content="/my-custom-path/images/govuk-opengraph-image.png"> – INVALID as the URL is not absolute

After

No meta tags would be included.

❌ Asset URL ❌ User-provided meta tag in head block ⚠️ Asset Path set to absolute URL

{# This is using assetPath incorrectly as we expect it to be a path, not a URL #}
{% set assetPath = "http://example.com/assets" %}

Before

One meta tag would be included:

• <meta property="og:image" content="http://example.com/assets/images/govuk-opengraph-image.png">

After

No meta tags would be included.

[querkmachine]

Of course, it might be that some social sharing sites 'do the work' to try and resolve it to an absolute URL anyway – if so this would break that. But in this instance I think we're better off following the spec and only including the meta tag if we know the absolute URL.

I whipped up some quick tests and tried 'em on a few random services, and it seems like some do resolve relative URLs to absolute ones, including Facebook's Meta's own validator (though this was inconsistent and did complain about it when trying with two relative images).

I agree that enforcing absolute URLs is the better way to go, though.

[NikhilNanjappa]

Hi guys

Sorry I'm not following what we need to do to get this working. We recently moved from 4.1.0 to 4.3.1 and we have never set the assetUrl or opengraphImageUrl.

If our app is hosted on different domains - https://my-app.dev.dwpcloud.uk, https://my-app.test.dwpcloud.uk, https://my-app.stag.dwpcloud.uk etc, are we supposed to set absolute paths of these domain names dynamically like so ?

{% set assetPath = "https://my-app.dev.dwpcloud.uk/govuk/frontend/assets/images/govuk-opengraph-image.png" %}

[36degrees]

@NikhilNanjappa

Most assets are intended to be loaded using relative paths, which means they use the assetPath variable which I think in your case should be /govuk/frontend/assets/.

However, the Open Graph images are different – because they're loaded by third parties they need to be absolute URLs. So, to get the Open Graph images to work, as well as the assetPath Nunjucks variable you should also set assetUrl to the absolute URL for the assets folder, like this:

{% set assetPath = '/govuk/frontend/assets/' %}
{% set assetUrl = "https://my-app.dev.dwpcloud.uk/govuk/frontend/assets" %}

Or, if you like:

{% set assetPath = '/govuk/frontend/assets/' %}
{% set assetUrl = "https://my-app.dev.dwpcloud.uk" + assetPath %}

As you've said, you'll need to be set assetUrl dynamically based on the environment.

(There is also the opengraphImageUrl variable, which you would use if your Open Graph image was somewhere else outside of the assets folder. If it helps understand how this works, you can see how they are used in the code here.)

[NikhilNanjappa]

Thanks @36degrees , thats what I had concerns regarding actually. Specifically getting the current domain value

{% set assetUrl = "https://my-app.dev.dwpcloud.uk" ...

I just find it a little weird as I would need to store that value dynamically in res.locals or similar and then use that in the nunjucks file.

[36degrees]

I just find it a little weird as I would need to store that value dynamically in res.locals or similar and then use that in the nunjucks file.

How would you expect it to work?

[NikhilNanjappa]

@36degrees probably use the relative path /govuk/frontend/assets/ by default and override it if user has provided assetUrl or opengraphImageUrl. Basically, if user has provided, use that or fallback to what you had pre 4.3.0 (/govuk/frontend/assets/)

This way projects aren't forced to now provide assetUrl or opengraphImageUrl with a minor upgrade.

[36degrees]

Relative Open Graph image URLs aren't valid according to the spec. We felt that the previous implementation was effectively a bug as we should only output an Open Graph meta tag if we believe it will be valid, and it can't be valid unless we know the full URL.

Our thinking around the impact of this change is documented in the original PR.

I appreciate the feedback about this change being rolled out in a minor release, and recognise we could have maintained the existing behaviour until v5.0. That was a judgement call the team made at the time, and we're not always going to get everything 100% right.

It's worth noting that if you don't expect users to be sharing links to your service on social media, you probably don't need the OpenGraph image.

[NikhilNanjappa]

Thanks @36degrees I see, I completely understand.

You're right, we are not expecting users to share the links anyways so its no biggie :)