Open Graph link preview image according to the document to open

@Mayaleeeee

OpenGraph Studio issue

Reason/Context

Thanks to the ?url=<url-of-file> and ?base64=<base64-encoded-doc> query param, Studio can load most of files (yes, not all of them, see #127). I expect users will use that to share their AsyncAPI docs.

Whenever a link to Studio (with or without those query params) is pasted into social media (Twitter, Linkedin, Facebook, Slack...), the preview image is this one:

It is a great pic, however it says nothing about the file being shared.

What if we could dynamically generate the preview image based on the file being shared? For example, the title, description and some stats could be shown.

I created a POC based on https://github.com/vercel/og-image (deprecated atm), available in my fork (It's just a POC) which is a server that generates dynamic images for being used on Open Graph image meta tags. This works by generating a dynamic HTML, making an screenshot of it through headless Chromium, and serving the resulting image.

The server accepts a ?base64=<base64-encoded-doc> query param, and generates an image that contains the AsyncAPI doc Title, Description, number of servers, channels and messages.

Despite the horrible design, the service is able to generate the following:

Based on the following AsyncAPI doc:

See

asyncapi: '2.2.0'
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  user/signedup:
    subscribe:
      message:
        $ref: '#/components/messages/UserSignedUp'
components:
  messages:
    UserSignedUp:
      payload:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

Open in Studio

Studio will need to modify the og:image tag so it points to this new service.

<meta property="og:image" content="http://<service-url>/*.png?theme=light&base64=YXN5bmNhcGk6ICcyLjIuMCcKaW5mbzoKICB0aXRsZTogQWNjb3VudCBTZXJ2aWNlCiAgdmVyc2lvbjogMS4wLjAKICBkZXNjcmlwdGlvbjogVGhpcyBzZXJ2aWNlIGlzIGluIGNoYXJnZSBvZiBwcm9jZXNzaW5nIHVzZXIgc2lnbnVwcwpjaGFubmVsczoKICB1c2VyL3NpZ25lZHVwOgogICAgc3Vic2NyaWJlOgogICAgICBtZXNzYWdlOgogICAgICAgICRyZWY6ICcjL2NvbXBvbmVudHMvbWVzc2FnZXMvVXNlclNpZ25lZFVwJwpjb21wb25lbnRzOgogIG1lc3NhZ2VzOgogICAgVXNlclNpZ25lZFVwOgogICAgICBwYXlsb2FkOgogICAgICAgIHR5cGU6IG9iamVjdAogICAgICAgIHByb3BlcnRpZXM6CiAgICAgICAgICBkaXNwbGF5TmFtZToKICAgICAgICAgICAgdHlwZTogc3RyaW5nCiAgICAgICAgICAgIGRlc2NyaXB0aW9uOiBOYW1lIG9mIHRoZSB1c2VyCiAgICAgICAgICBlbWFpbDoKICAgICAgICAgICAgdHlwZTogc3RyaW5nCiAgICAgICAgICAgIGZvcm1hdDogZW1haWwKICAgICAgICAgICAgZGVzY3JpcHRpb246IEVtYWlsIG9mIHRoZSB1c2Vy" />

The preview image would then look like (note that https://shaggy-stingray-56.loca.lt/ was a local tunnel to my localhost serving a simple html with the og-image tag):

By the way, all of this could run on serverless functions such as the Netlify functions (which are AWS Lambda) available in free tier :)

Description

Here is a sequence diagram showing the big picture of the flow a request made by an Open Graph crawler (crawlers used for querying the open graph image whenever you share a link) will follow:

sequenceDiagram
Open Graph Crawler->>+Studio: /?base64=<encoded_doc>
Studio->>Studio: Set og:title, and og:description metatags. Set og:image to <og-generator-service>/generate.png?title=foo&description=bar&operations=4&servers=2 
Studio->>-Open Graph Crawler: Pre-rendered Studio HTML webpage
Open Graph Crawler->>+OpenGraph Generator: <og-generator-service>/generate.png?title=foo&description=bar&operations=4&servers=2 
OpenGraph Generator->>-Open Graph Crawler: og-image.png

Note that, as explained in this comment, we would need to configure pre-rendering in Netlify for doing the og:image content URL replacement on each request made by a crawler.

Alternatively, whatever technology we use (for example NextJS), the flow for rendering the Studio page would be something like the following:

flowchart TD
    A[User] --> B(https://studio.asyncapi.com)
    B --> C{contains ?base64 or ?url}
    C -->|No| D[Static rendering]
    C -->|Yes| E[Dynamic rendering]
    E --> F(Parsing AsyncAPI doc + etc)

In case the image can't be generated due to whatever reason, the default AsyncAPI Studio should be served instead: https://studio.asyncapi.com/img/meta-studio-og-image.jpeg

What you will need to do

Note that the design of the Open Graph image card is also part of this task. Ask @Mayaleeeee for help on this (Thanks! 🙌 ).

Prerequisites

Fork Studio.
Deploy it to your own Netlify free account. I recommend you to do it via Netlify’s website UI and not via Netlify CLI. With few clicks your site will be configured to be deployed on each push to the branch you specify.
Enable Prerendering in your new Netlify site. This will allow web crawlers (such as the ones used for fetching the OpenGraph meta tags) receive a fully rendered version of the website, including content loaded by Javascript.

Work to do

Create a new Github repository where your Open Graph image generator service will be tracked.
Create then a new service that exposes an HTTP API that generates an Open Graph image based on few query params (use the names you want, the following are just suggestions):
1. doc_url: a URL pointing to a raw AsyncAPI document.
2. doc_base64: an AsyncAPI document encoded in base64.
Some hints:
- You will need to use the AsyncAPI Parser-JS to parse your document and extract the data you need from it
- In order to generate the image, you can use @vercel/og package. (og-image is deprecated now). Documentation on how to use it is available here. Alternatively, if that package is not compatible in a non-vercel world, you might want to take a look to https://github.com/vercel/satori, which is what that package uses under the hood.
Deploy this new service somewhere. I recommend you to deploy it via Netlify Functions. Or even better if we can get it as a Netlify Edge Function (support of npm packages is still experimental) since I believe we will be able to implement a caching mechanism easily.
Once we have a public URL of that service, include a Javascript code somewhere in the Studio website that modifies the og:image meta tag content to point to the new service URL including the doc_url or doc_base64 query param with the right content. That will be the trick that will make the OpenGraph image shown dynamically based on such parameters.
Performance is a must. Both serving the Open Graph tags + generating the image should not take more than few secs (~3), otherwise crawlers will timeout (for example, Slack's crawler timeouts at 5 secs)
Investigate about caching. If hosted as a Netlify function, I believe we could just trust in cached responses. See https://docs.netlify.com/platform/caching/#supported-cache-control-headers. Otherwise, we could give a try to Netlify Blobs and store each generated image using the base64 hash (or a reproducible and atomic hash) so every new request first check if that image is already generated and in the case it is, serve the blob directly (not 100% if this use case can be supported, but I guess it is).

Anyway, more investigation on how to implement the service should be taken, so please do not take my words here as the right way to do it as I didn’t spent time on it when I created this issue.

GSoC 2024

This issue got accepted as part of the GSoC 2024. @helios2003 is assigned as mentee.

We are using the following read-only Project board to track the current status of it's work: GSoC 2024 Tasks (view)

Hope I'm not butting in too much but in case you guys want a quick and easy solution for this (until you develop your own), you can use https://thumbsmith.com/

(Full disclaimer - I'm the founder 😬 )

Usually this is more for websites that can't easily deploy services like you guys tho (eg: wordpress sites)

@smoya

@smoya Thanks for that awesome idea! I understand implementation of that but the main problem in current solution (how Studio works) is that we have full SPA application, so everything is loaded and resolved in the runtime in the JS, so even if we update og:meta in the head of the page the web crawlers (like in fb for og:meta) will have already read this metadata and will not wait for JS to load and execute. I don't know how to get around this problem. One of the possible solutions could be to intercept the server-side request and check if the queryer is e.g. a crawler and return him the appropriate html with the appropriate metadata, but for this we should have a simple server.

@loteoo Hi and thanks! :) It may sound stupid, but in your solution there is a support for SPA applications that would change this metadata at runtime (see my comment above)?

@magicmatatjahu

Hi @magicmatatjahu, my pleasure! Unfortunately as you mentioned the meta tags really needs to be in the initial HTML for the crawlers to pick it up. You will have to do SSR, or wait for something we had actually planned on our roadmap similar to this. (But you will have to share a custom URL, not the original URL)

@magicmatatjahu

@magicmatatjahu as we are hosting the Studio in Netlify, we can make use of prerendering which will prerender pages when those are requested by crawlers. See https://docs.netlify.com/site-deploys/post-processing/prerendering/

EDIT: I tested this creating a new site from Studio in my personal Netlify account. Just by enabling prerendring and adding a simple js script, we can make it work:

<script>
      const params = new URLSearchParams(window.location.search)
      if (params.has('base64')) {
        document.querySelector('meta[property="og:image"]').setAttribute("content", "https://example.com/?base64=" + params.get('base64'));
      }
    </script>

Source: https://github.com/smoya/studio/blob/master/public/index.html#L32-L37
replace example.com with the preview image service URL we would deploy

curl "https://hopeful-liskov-2a657c.netlify.app/?_escaped_fragment_=&base64=BASE64HERE" | grep og:image

...

<meta property="og:image" content="https://example.com/?
base64=BASE64HERE">

@smoya

@smoya https://www.youtube.com/watch?v=9CS7j5I6aOc Can I say that we are in home? 😄

@smoya

@smoya So, do you wanna handle that feature and create such a lambda for Netlify? I don't know where we should keep the source code of this lambda, in the Studio or as a new repo in the organization?

@smoya

@smoya So, do you wanna handle that feature and create such a lambda for Netlify? I don't know where we should keep the source code of this lambda, in the Studio or as a new repo in the organization?

The pros of having it in this repository is that it will be always in sync with the code and everything will be handled by Netlify at the deploy level.
The cons is that we will be adding more code to this repository that is not really needed for running Studio.
I still need to cleanup the code so I would say if the final code is not so big, I would advocate for adding it to this repository.

WDYT?

@smoya

@smoya then we have it in this repo :)

@mcturco

@mcturco I would like to ask you if you could help me with the design part for this.

@smoya

@smoya yes, I can help out with a design for this! Are there any limitations as far as layout/styling goes? I will use your example images to reference what content will be included, but was just wondering how it would be implemented since I see the open graph image is gathering meta information and not using HTML (unless I am incorrect?)

@smoya

@smoya yes, I can help out with a design for this! Are there any limitations as far as layout/styling goes? I will use your example images to reference what content will be included, but was just wondering how it would be implemented since I see the open graph image is gathering meta information and not using HTML (unless I am incorrect?)

Those images I attached are generated from HTML. What we need is to design those cards in HTML (CSS, TS, whatever).
The HTML used for those images is located here.
I guess we could ask @magicmatatjahu or any other user from the community to help with that part, but still the design is needed.
The minimum size would be 1200 x 630 (as recommended for high-res displays).

About the data we can display on it, I'm up to suggestions. I thought on:

Title and version
Description (truncated) - (Should we render markdown?)
Num of Servers
Num of Channels
Num of ~~Publish~~ Send operations
Num of ~~Subscribe~~ Receive operations
Num of Messages

Anything you all think we could add/remove from it? (we should try to avoid overloading the image, so some could be drop if needed).

@smoya

@smoya sounds good! yeah just wanted to make sure that I can apply some of the new styles that we have been using as part of the brand refresh. Cool! I can get to work on that 😄

Hi all! Sorry for the delay on my part for this issue. Going to add this back onto my list as we are working towards launching the new brand stuff. I will be using the new logo/colors/typography for this open graph 👍

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

@helios2003

Just for the record, @helios2003 got selected as GSOC 2024 Mentee and it is working on this issue.

I have run some performance tests between the current production instance of studio-next and my deployed instance of studio, which parses the content at the studio level (see the issue description) to dynamically set the open graph tags. My deployed instance of studio can be found here: https://studio-helios2003.netlify.app.

Without `base64` document in the URL params

Metric	https://studio-next.netlify.app	https://studio-helios2003.netlify.app
Time to first byte	356 ms	345 ms
First Contentful Paint	606 ms	549 ms
Onload time	1400 ms	1300 ms
Largest Contentful Paint	2900 ms	2600 ms
Time to be Interactive	3200 ms	2900 ms
Fully loaded time	4100 ms	4100 ms

With `base64` document in the URL params

Metric	https://studio-next.netlify.app	https://studio-helios2003.netlify.app
Time to first byte	284 ms	2600 ms
First Contentful Paint	426 ms	2800 ms
Onload time	1200 ms	3500 ms
Largest Contentful Paint	4100 ms	6700 ms
Time to be Interactive	3200 ms	5800 ms
Fully loaded time	4200 ms	6700 ms

the base64 doc used can be found here: https://tinyurl.com/57dexzrd

@helios2003

@helios2003 what was the approach here? parsing the document twice?

Nope, the document is being parsed once.

@helios2003

After checking @helios2003 tests, I ran a simple comparison test measuring the response time from https://studio.asyncapi.com and https://studio-next.netlify.app.

The Studio URL was always the same @helios2003 provided in its tests, which loads an AsyncAPI via the base64 query param.

Look at the results:

Version	Cache-Status	Time Total (seconds)
Studio (regular)	"Netlify Edge"; fwd=miss	0.316334
Studio-next (NextJS)	"Next.js"; hit,"Netlify Edge"; fwd=stale	4.156618

As you can see, the Next-JS version takes almost 4 seconds more than the regular version. I could understand the timing because almost everything is rendered at server level. However, I don't understand the Cache-Status response header then. It says there is a cache HIT. But how so? If it's a hit, I would expect the response to be a prebuilt one. In that case, the response would have to take much less than that.

Any idea why this is happening? @KhudaDad414 @Amzani

@helios2003

@helios2003 What about intercepting the request made by opengraph crawlers and print, in that case, only the headers? In that case, no extra javascript would be needed to be rendered. Then, I expect the response time should be way lower than 5s

@helios2003

@helios2003 What about intercepting the request made by opengraph crawlers and print, in that case, only the headers? In that case, no extra javascript would be needed to be rendered. Then, I expect the response time should be way lower than 5s

On doing that this is the result.

The time taken is much larger for the first request but reduces substantially for the subsequent calls to the same endpoint. This contains the doc specified in the above message.

On doing that this is the result.

~5 seconds to parse the doc + print basic headers it's too much. Are you sure only required headers are being printed? (no headers loading scripts, etc)

The time taken is much larger for the first request but reduces substantially for the subsequent calls to the same endpoint.

That's due to the cache at Netlify's edge. If you print the cache-status response header, you will notice a hit.

@helios2003

Update: The diff regarding time response in Netlify VS Vercel is so noticeable. After the creation of #1118, @helios2003 is gonna keep working on the main assigned task (this issue) and most probably keep deploying it's changes to both Netlify and Vercel to avoid unexpected performance issues.

Meanwhile, I expect the owners of Studio to prioritize the investigation.

cc @magicmatatjahu @KhudaDad414 @Amzani

@Mayaleeeee

@Mayaleeeee seems to be out until the first week of August (as per its absence in Slack and its Slack status message). I hope she can then work on providing the design for the OG card and be on time for the GSOC timeline.

cc @helios2003

Proposed scope for Advanced / Coding:

Add document-specific OG metadata for URL/load, base64 and share links on Netlify.
Generate a compact application card using Studio’s existing styling: title, version, protocol, short description, two operation/channel tiles and counts.
Include safe fetching, bounded parsing, caching and static fallback.
Verify first-request/cached performance and editor behaviour, covering Response time for NextJS version seems too high #1118. Keep Docker/Vercel previews static.
Add tests and maintainer docs.

Why Advanced: this spans server-side metadata in a static app, secure fetching/parsing, image rendering, cache isolation and hosted performance checks. Cold starts and timeouts need to be handled while keeping the editor usable.

Example:

Navigation Menu

Repository navigation

Open Graph link preview image according to the document to open #224

OpenGraph Studio issue

Reason/Context

Description

What you will need to do

Prerequisites

Work to do

GSoC 2024

60 remaining items

Without `base64` document in the URL params

With `base64` document in the URL params

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Open Graph link preview image according to the document to open #224

Description

OpenGraph Studio issue

Reason/Context

Description

What you will need to do

Prerequisites

Work to do

GSoC 2024

Activity

loteoo commented on Jan 10, 2022

magicmatatjahu commented on Jan 10, 2022

loteoo commented on Jan 10, 2022

smoya commented on Jan 10, 2022

magicmatatjahu commented on Jan 10, 2022

magicmatatjahu commented on Jan 10, 2022

smoya commented on Jan 10, 2022

magicmatatjahu commented on Jan 11, 2022

smoya commented on Jan 12, 2022

mcturco commented on Jan 12, 2022

smoya commented on Jan 12, 2022

mcturco commented on Jan 12, 2022

mcturco commented on Mar 8, 2022

github-actions commented on Jul 7, 2022

60 remaining items

smoya commented on May 31, 2024

helios2003 commented on Jun 11, 2024

Without base64 document in the URL params

With base64 document in the URL params

KhudaDad414 commented on Jun 11, 2024

helios2003 commented on Jun 11, 2024

smoya commented on Jun 11, 2024

smoya commented on Jun 11, 2024

helios2003 commented on Jun 12, 2024

smoya commented on Jun 13, 2024

smoya commented on Jun 17, 2024

smoya commented on Jul 29, 2024

Shurtu-gal commented on Oct 13, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Without `base64` document in the URL params

With `base64` document in the URL params