WordPress plugin

The DataFlair Toplists plugin is a working client of the Toplist API. It fetches your toplists and brands from DataFlair, stores them in your WordPress database, and renders them with a block or a shortcode. It makes no call to DataFlair when a visitor loads a page.

This is the fetch-ahead pattern described in the Integration model. The plugin also applies the geo rules in Geo-targeting and compliance when it renders.

Requirements

• WordPress 6.3 or later
• PHP 8.1 or later
• MySQL 5.7 or later, or MariaDB 10.3 or later, for JSON columns

Install

1. Upload the dataflair-toplists folder to /wp-content/plugins/.
2. Activate the plugin in Plugins, then Installed Plugins.
3. Connect it to your tenant. See the next section.

The plugin includes its dependencies, so you do not run composer install on the server.

Connect

Go to DataFlair, then Settings, then the API Connection tab.

Field	What to enter
API Bearer Token	Your DataFlair API bearer token. Use the static token. See Authentication.
API Base URL	Your tenant URL with the API path, for example https://tenant.dataflair.ai/api/v1. Leave it empty to let the plugin detect it from the token.
Brands API Version	v1 or v2 of the brands endpoint.

Click Test Connection. It checks the toplists endpoint, which always uses v1. It does not exercise the Brands API Version you chose.

A wrong token gives 401. A token without the toplist:read scope gives 403. See Error handling.

Sync

The plugin copies data from DataFlair into three tables in your database: wp_dataflair_toplists, wp_dataflair_brands and wp_dataflair_alternative_toplists.

Start a sync in one of two ways:

• In WordPress. On DataFlair, then Dashboard, click Sync Brands and Sync Toplists.

• With WP-CLI.

  wp dataflair sync                    # everything
  wp dataflair sync --only=toplists    # toplists only
  wp dataflair sync --only=brands      # brands only

  The command exits with a non-zero code when it fails, so a real cron job can react. It backs off on API rate limits.

The plugin has no automatic WP-Cron schedule. To sync on a schedule, add the WP-CLI command to your server crontab. The Sync Schedule tab in Settings shows an example, and it holds a retry count and an alert email.

Webhook sync

On the API Connection tab, tick Enable webhook sync. DataFlair then pushes changes to your site as they happen, instead of waiting for the next sync. The plugin registers your site with DataFlair, and it reuses your API token. A delivery is signed with HMAC-SHA256 and verified before anything else runs. A repeated delivery does nothing.

Place a toplist

Block. Add the DataFlair Toplist block to a page or post. In the block settings, choose a toplist and set an item limit.

Shortcode.

[dataflair_toplist id="123" limit="10"]

Attribute	Required	Meaning
id	yes, unless you use slug	The DataFlair toplist ID.
slug	no	Look the toplist up by its slug instead of its ID.
title	no	Replaces the display title of the toplist.
limit	no	The most brands to show. The default, 0, shows all.

The shortcode also accepts layout, ctaMode, template and auto_geo.

Test this

Add a toplist to a page and view it while logged out. The plugin reads from your database, so a missing toplist means the sync did not run or did not finish. Check DataFlair, then Dashboard, for the last sync time, and Tools for the API Contract Check diagnostic.