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:

templates/main.js

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.
• :version — The version control number of your deck.
  • Defaults to _ which means latest version.
  • Omit to always use the latest version (recommended).

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.