Concepts
Let's speak the same language.
Glossary
Here is the list of the technical terms.
Flyyer
The name of the service but also we call "flyyer" any smart image generated by our service. We are composed by three main services:
- Dashboard (
www.flyyer.io/dashboard
) โ Dashboard, billing, account management, project setup, og:image preview and management; and social image generation UI. - Flyyer CDN (
cdn.flyyer.io/v2/
) โ Our main service, your og:images should point to Flyyer CDN so we can scan your website and render images when your are being shared on social media. - Flyyer Render (
cdn.flyyer.io/render/v2/
) โ Template rendering server. Content provided explicitly through variables for full customization. It is more imperative because you need to explicitly setup the calling parameters and variables to create images. Flyyer CDN uses this service but takes contextual values from your website and applies the rules defined on Flyyer.io.
Slug
The machine-friendly version of a text. Example: Hello there!
as slug would be hello-there
.
Identifier
Synonym of Slug.
Template
This is the most important thing about Flyyer. This is in reality a webpage (HTML, CSS and JavaScript) acting as a template to create dynamic images . What is great about this templates is that you can use them to generate infinite amount of images based on variables.
For developers and engineers: a template is a web component (React, Vue, etc). To develop templates you can start a project following this section. Every template has a name corresponding to the name of its file (similar to Next.js and pages).
Take a look at this example, here we have a template with multiple variables and some of all the possible outcomes:
Variables
These templates receives variables as input and renders images based on those inputs. This is way more smarter than other image services whom only allows to compose images, add watermarks, etc. You can do all of that and even more with custom login and your own styles.
Variables are passed through the unique URL of a flyyer as queryparams. Eg: This is an actual URL of a Flyyer with a param title
:
https://cdn.flyyer.io/render/v2/flyyer/charming-man/main.png?title=Title
Inside the component it looks like this:
import React from "react";
export default function DemoTemplate({ variables }) {
const title = variables.title; // ๐ variable from queryparams
return <h1>{title}</h1>;
}
tip
To read more about variables and how to support objects and array go to Complex variables.
Schema
The next level of variables. The problem with plain variables is that they are hard to discover and you can receive unwanted inputs.
Example: a variable price
would expect an number
but when serialized as queryparam it becomes price=20
which is indistinguishable from "20"
as a string
.
We created @flyyer/variables so you can known what you can send to a template and being able to parse inputs to their correct types.
You only need to export an schema
object from your template files.
import { Variable as V, Static, Validator } from "@flyyer/variables";
export const schema = V.Object({
title: V.String({ description: "Displayed on https://flyyer.io" }),
description: V.Optional(V.String({ default: "Hello world" })),
image: V.Optional(V.Image({
description: "Image URL",
examples: ["https://flyyer.io/logo.png"],
})),
});
const validator = new Validator(schema);
type Variables = Static<typeof schema>; // Typescript users
export default function Template({ variables }: TemplateProps<Variables>) {
const {
data: { title, description, image } // safe values! ๐
} = validator.parse(variables);
// ...
}
It will look like this on your Flyyer Dashboard:
Deck
A deck is a collection of Templates. The idea of a deck is being able to share common styles, components and code between many templates. Each deck is identified by a slug defined in flyyer.config.js
.
Tenant
Every user belongs to an organization. We call this entities "tenants" or "companies" for simplicity. Each tenant is identified by an unique slug, eg: my-company
. Each tenant has many Decks.
Tenants can also be single users.
Each tenant has a public profile with their public templates at Flyyer Community.
Company
Synonym of Tenant.
URL anatomy
Flyyer CDN
Flyyer Render
Every FlyyerRender URL is built around this schema. For variables refer to Variables and Complex variables.
:tenant
โ is the Tenant's slug:deck
โ is the Deck's slug:template
โ is the Template's slug:extension
โ the extension of the rendered image- Possible values:
png
,webp
,jpeg
(jpg
is an alias) - Defaults to
jpeg
.
- Possible values:
:version
โ The version control number of your deck.- Defaults to
_
which means latest version. - Omit to always use the latest version (recommended).
- Defaults to
Variables are passed down as queryparams.
note
Please note that :tenant
, :deck
and :template
are always required, everything else is optional.
Short format
Shortest form: always latest version and defaults to .jpeg
format.
https://cdn.flyyer.io/r/v2/:tenant/:deck/:template?variable=value
# Example:
https://cdn.flyyer.io/r/v2/flyyer/landing/demo?title=Title
Long format
Longest form: explicit version and extension. The namespace /r/
is an alias of /render/
.
https://cdn.flyyer.io/render/v2/:tenant/:deck/:template.:version.:extension?variable=value
# Example:
https://cdn.flyyer.io/render/v2/flyyer/landing/demo.1608497482.png?title=Title&description=Description+text
tip
To easily compose and format Flyyer URLs please use one of our libraries.