Content Delivery API

SEO and favicon fields

While you can fetch the content of a "SEO and Social" field just like any other field, the GraphQL API exposes on every record a much simpler _seoMetaTags field that you can use to easily get HTML meta tags based on the information present in the record itself:

{
  blogPost {
    _seoMetaTags {
      tag
      attributes
    }
  }
}

How are `_seoMetaTags` generated?

Meta tags are generated merging the values present in the record's "SEO and Social" field, together with the global SEO Preferences that you can configure in the Content tab.

If the record doesn't have a "SEO and Social" field, the method tries to guess reasonable values by inspecting the other fields of the record (single-line strings and images).

title, og:title, twitter:title

These titles can be explicitly set in the "SEO and Social" field, if present. If the record does not have that SEO field, or the title is not specified, the tags will be generated from either the record title or the title provided in the global SEO settings.

The Title suffix value from global SEO preferences will also be concatenated to the titlefield, as long as the total length of the title + suffix is 60 characters or less. If the combined length is longer, the suffix will be omitted.

The suffix will NOT be added to the OpenGraph and Twitter titles, since there are already other fields for that (og:site_name and twitter:site).

If needed, you can manually query for the suffix:

_site {
  globalSeo {
    titleSuffix
  }
}

description, og:description, twitter:description

These tags are generated using the description field in the "SEO and Social" field. If no such field is present, or the description is not specified, the tags will be generated from the description specified in the global SEO settings.

og:image, og:image:width, og:image:height, og:image:alt, twitter:image, twitter:image:alt

These tags are generated using the image field in the "SEO and Social" field. If no such field is present, or the image is not specified, the tags will be generated from the image specified in the global SEO settings.

robots noindex

A robots noindex tag will be added if either global SEO Preferences or the "SEO and Social" field have a "Prevent from being indexed by search engines" enabled.

og:locale

This tag is generated using either the locale specified in the query filter, or the main locale.

og:type

If the model is a singleton an og:type of type website will be returned, otherwise an og:type of type website will be returned.

og:site_name

The tag is generated from the site name attribute (if provided)

twitter:site

The tag is deduced from the twitter_account attribute (if provided)

twitter:card

The tag is generated from using the twitter_card field in the "SEO and Social" field. If no such field is present, the global SEO settings will be used.

article:modified_time

This tag is generated using the updated_at meta attribute of the Record

article:publisher

The tag is deduced from the facebook_page_url attribute (if provided)

SEO title & image fallback rules (with automatic fallback)

For SEO purposes, our basic philosophy is that having some relevant SEO is better than none at all. Thus, if a record is missing an explicit SEO title or image, we will try to automatically guess a value for you using the record's own content. This may be surprising at first, because this automatic fallback happens before your project-level SEO preferences are consulted. This section describes how this automatic fallback chain works.

How SEO title fallback works

We check these places, in order, and pick the first non-blank value:

We always prefer the record's own SEO field, if it has one, and if its title is set. If the record has 2+ SEO fields, we only look at the first field (alphabetically by API key) and ignore the others.
Otherwise, we automatically pick a fallback field, in this order:
- The "SEO fallback title" field in the model settings, under the SEO tab, if one is set
- The first (by API key) single-line string field with "Show as heading?" enabled in its field settings (under the Presentation tab)
- The first single-line string field (regardless of its Presentation settings).
First we pick that field, then we check whether it has a non-blank value. If so, we use it. If not, we skip all other fields and proceed to the next step.
Last resort: the project's own "SEO preferences" (in the left sidebar). We only check here if ALL the previous checks failed.
If all of the above are empty, we altogether omit title from the _seoMetaTags array.

How SEO image fallback works

We check these places, in order, and pick the first usable image (see below for what "usable" means):

We always prefer the record's own SEO field, if it has one, and if its image is set. If the record has 2+ SEO fields, we only look at the first field (alphabetically by API key) and ignore the others.
Otherwise, we automatically pick a fallback field, in this order:
- The "Fallback social card image" field designated in the model settings, under the SEO tab, if there is one.
- The first (by API key) asset or gallery field with its "Accept only specified extensions" validation set to "Image (including SVG)". (The "Raster image, transformable by imgix" option does not count here.)
- The first asset or gallery field (regardless of its validations).
First we pick that field, then we check whether it has a usable image or video thumbnail. If so, we use it. If not, we skip all other fields and proceed to the next step.
Last resort: the project's own "SEO preferences" (in the left sidebar). We only check here if ALL the previous checks failed.
If all of the above are empty, we altogether omit og:image, og:image:width, og:image:height, og:image:alt, twitter:image and twitter:image:alt from the _seoMetaTags array.

What counts as a usable image: the asset must be an image (including SVGs) or a video with a thumbnail. At any step, if the asset is another type (PDF, audio file, a video that's still awaiting processing and thumbnail creation, etc.), we skip it and move on to the next step, exactly as if it were empty.

SEO description fallback rules

The fallback system for the SEO description is much simpler, compared to the system for titles and images above. We check, in order, for the first non-empty value:

The record's SEO field description
The model's designated excerpt field, if one is set in the model's SEO tab. We convert this to plain text and truncate it 200 characters.
The sitewide default description set in the main sidebar's SEO preferences settings.
If none of the above have a value, the description tag is dropped from the _seoMetaTags array.

Favicon meta tags

Similarly, you can get the meta tags needed to properly show the site's favicon with the _faviconMetaTags attribute contained inside the _site field:

{
  _site {
    faviconMetaTags {
      tag
      attributes
    }
  }
}

iOS and MS app icons

If you're building an app, you can request additional meta tags with the variants argument:

{
  _site {
    faviconMetaTags(variants: [icon, appleTouchIcon, msApplication]) {
      tag
      attributes
    }
  }
}

See an example of how the SEO meta tags are generated in Next.js.

Want to know more about SEO customization in DatoCMS? Check out this video tutorial:

Working with and customizing SEO Fields

Play video »