Canonical component · three layers
One “Manage Sources” card everywhere. Base states every plugin shares → the same row flexing per plugin family (real account types, labels, and error strings from the plugin sources) → the legacy baggage, unified under one warning-token treatment. Expand Spec under any state for triggers, actions, and grounding.
Instagram shown as the demo family; swap the avatar, accent, and noun per plugin. The anatomy never changes: avatar · name · status line · actions.
Add or remove connected Instagram accounts.
Trigger: source has a working token; last API call succeeded. Actions: add another source, or remove this one (confirm — feeds using it warn).
Add or remove connected Instagram accounts.
Looks like you have not added any source.
Use “Add Source” to add a new one.
Trigger: fresh install, or every source removed — feeds can’t render without one. Actions: one action, no dead ends: start the connect flow.
Existing Instagram empty-source string. The connect flow never asks for a password: “This does not give us permission to manage your account, it simply allows the plugin to retrieve public content from the API.”
Add or remove connected Instagram accounts.
Trigger: user launched the OAuth flow; resolves to B1 or B4 when the redirect returns. Actions: cancel, or complete authorization in the popup.
Grounded in the existing redirect interstitial: “Redirecting to connect.smashballoon.com — you will be redirected to our app so you can connect your account in 5 seconds” (Instagram builder).
Add or remove connected Instagram accounts.
There was an error when trying to connect to Instagram. Your existing sources were not changed, and feeds will keep showing cached posts.
Trigger: connect flow or API call failed for a non-token reason (outage, HTTP error, unexpected response). Existing sources keep serving cached posts. Actions: Try Again, View error (for support).
Headline is the existing errorNotice string. “View error” surfaces the last-10-entries error log already kept by the Facebook/Twitter error reporters.
Add or remove connected Instagram accounts.
Trigger: the API says the source itself is unusable — token expired, revoked, or undecryptable after a site move. Actions: Reconnect (repeats OAuth in place, keeping feeds and settings), or Remove.
Both messages are real: “Invalid Access Token. Please reconnect the source.” (TikTok SourceErrors) and “Your access token could not be decrypted on this website. Reconnect this account…” (Instagram). TikTok centralizes the reconnect-worthy codes — access_token_invalid, token_decrypt_failed, “The payload is invalid.”, “The MAC is invalid.”, “Could not decrypt the data.” — the converged standard for every family.
The component flexes on exactly three axes: identity (avatar/handle/ID), type tag (Business, Page, Group, Place ID…), and platform-imposed states. Nothing else may vary. Pick a family:
Add or remove connected Instagram accounts.
Facts: OAuth via connect.smashballoon.com; account type matters — a live personal source is automatically in a deprecation state; a revoked source starts a 7-day countdown, then L6.
All three grounded: “Action required. Reconnect as a business account” + Dec 2024 notice (feed builder); the revoked-permission 7-day deletion window with automatic data wipe (posts manager / Platform_Data).
Add or remove connected Facebook pages and groups.
Facts: sources are Pages or Groups; group sources carry a standing 90-day limit and a deprecation state pointing at Pages as the migration path.
Grounded: the 90-day note (“Due to a Facebook API limitation, only content posted to this group in the past 90 days can be displayed”) and the group_deprecation error + dismissible notice in CFF_Error_Reporter. Groups used a separate login endpoint (facebook-group-login.php) — converged flow keeps one Add Source button and asks Page vs Group inside it.
How this site fetches data from the X API.
ctf4a2b… · used to fetch data from the X API
Due to X API changes, feed updates are limited to once a week on this connection. Connect your own X app to update more often.
Your own X developer app credentials (Pro).
Requires an X developer account on a paid API tier. Feeds fall back to the site key if these credentials stop working.
Facts: after the X API pricing change there is no per-account OAuth. Lite fetches through a Smash Balloon site key relay capped at weekly updates; Pro users can connect their own X app (v2 credentials) to update more often.
All labels shipping today: “Site Key — this is used to fetch data from the Twitter API”, “Refresh”, “Connect your Own App (V2)”, “Connected Twitter App”, the four credential fields, and “Due to Twitter API changes, we have to limit feed updates to once a week”.
Connect a channel and provide a YouTube API key.
Facts: feeds run keyless on a limited RSS fallback, but most features need a Google API key; a channel can also be connected as an identity source.
Grounded: “Important: No API Key Entered.” (settings), “Unable to retrieve new videos without an API key” + RSS fallback (RSS_Connect), AJAX key validation. The OAuth channel row is inferred in its details — the connect flow exists but its states weren’t verifiable in this snapshot.
Add or remove connected TikTok accounts.
Facts: OAuth accounts keyed by open_id; one class defines which errors demand a reconnect and every surface reads from it.
The reconnect-worthy codes live in one place (SourceErrors): access_token_invalid, token_decrypt_failed, “The payload is invalid.”, “The MAC is invalid.”, “Could not decrypt the data.”
Connect review platforms and manage collections.
Facts: sources are review platforms (Google, Yelp, Trustpilot, TripAdvisor, Facebook, WordPress.org) identified by Place ID / business URL, gathered into collections. Some platforms need an API key; some are gated by plan tier (cross-ref license state 09).
Grounded: “Place ID” field, “Manage API Keys”, “New reviews will not display until an API key is entered for your sources” + “How to create an API key”, “Import Collection”, Yelp tier gate (“Upgrade to our ‘Plus’ tier…”).
Feeds from your other Smash Balloon plugins.
Facts: a wall’s sources are the feeds of the other Smash Balloon plugins, so each row can additionally be “not installed” or “incompatible version” — states no other family has.
Grounded in the configure template: “The version of the Instagram Feed plugin you are using is not compatible with the Social Wall plugin and needs to be updated” + “Update Instagram Plugin”, “Install Instagram Plugin”, “Don’t have this plugin? Get it now”, per-row “Remove”.
Add or remove connected Threads accounts.
Facts: newest plugin, no history to carry — proof the standard needs zero exceptions when legacy doesn’t force them.
inferred The Threads reference checkout is empty in this snapshot, so this section is designed to the standard rather than extracted from code — intentionally: greenfield means base states only.
Two kinds of baggage exist in the code: legacy feeds (shortcode-era, pre-feed-builder — Instagram pre-v6, Facebook pre-v4, Twitter equivalent; one global settings blob, undeletable from the UI) and legacy sources (old options-format accounts batch-migrated to the sources table, plus sources on APIs the platforms have sunset). Every legacy state uses warning tokens with a dashed border — recognizable at a glance, never red (nothing is broken), always paired with a migration path.
Feeds created before the feed builder.
3 legacy feeds are running on this site. Legacy feeds are older feeds from before the feed-builder update — these settings apply to all of them at once, just like they did before. What are legacy feeds?
Trigger: the feed locator finds pre-builder feeds rendered via shortcode. Actions: open the shared legacy settings (one blob applies to all), or learn what legacy feeds are.
Grounded: Instagram “Legacy feeds are older feeds from before the version 6 update…”, Facebook “…before the version 4 update” + “These settings will impact N legacy feeds on your site”; all three families count legacy feeds via feed locators. “Convert to feeds” is inferred — today only the shared Settings button exists.
Feeds created before the feed builder.
Trigger: user tries to delete a legacy feed from the admin — it can’t be. Actions: see exactly where it’s embedded (feed-locator data) and remove the shortcode there.
Copy grounded: “To delete a legacy feed, simply remove the shortcode wherever it is being used on your site.” (Instagram builder). Locations come from the feed-locator tables that already track where each feed renders.
Add or remove connected Instagram accounts.
Trigger: after updating across the source-model rewrite. Actions: none — informational; sources appear as they convert.
Mechanism grounded: legacy_source_queue / batch_process_legacy_source_queue (Instagram) chunks old connected_accounts per admin load. The user-facing copy is inferred — today this runs silently.
Add or remove connected Instagram accounts.
All set. 2 accounts connected in an earlier version were moved to the new source system. Feeds were not affected.
Trigger: the migration queue drains. Actions: dismiss, or review the migrated sources.
inferred No confirmation string exists in the code — the queue just empties. Designed so the silent migration becomes legible instead of invisible.
Sources on deprecated platform APIs.
Trigger: the source still works (or half-works) but its API is sunset: Instagram personal (Dec 2024), Facebook Groups, Twitter site-key-only fetching. Actions: one-click migration path; cached content keeps serving meanwhile.
Deprecations grounded per family (see P1–P3). The uniform “migration path” row is the convergence — today each plugin announces these in a different-looking admin notice.
Add or remove connected Instagram accounts.
Trigger: a revoked source (P1’s 7-day window) was not reconnected in time; all cached data was wiped per Meta rules. Actions: Reconnect to start fresh, or Remove the dead source.
Grounded: the platform_data_deleted error — “The page was not reconnected within the 7 day limit and all Instagram data was automatically deleted on your website due to Facebook data privacy rules… To fix your feeds, reconnect all accounts that were in use.” Reviews carries the same Facebook-sourced state.