=== SocialCards ===
Tags: open graph, social media, social image, og image, woocommerce
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate Open Graph images from SocialCards templates using WordPress content, rules, automation, and WooCommerce mappings.

== Description ==

SocialCards connects WordPress to the [SocialCards service](https://social.cards/) to generate social images from reusable visual templates. Map WordPress content into template variables, preview current edits, and save generated PNGs in your WordPress Media Library.

A SocialCards Pro account and API key are required to connect WordPress, access saved templates, use Preview/rendering, and run automatic or bulk generation. Account, template, and rendering functionality is provided by the external SocialCards service. You can install the plugin without connecting; onboarding and preserved local configuration/images remain available, but API-dependent actions require a connection.

Features include:

* Posts, Pages, and enabled supported public custom post types.
* Text mappings for titles, excerpts, author display names, publication dates, site names, and custom text.
* Image mappings from local Featured images, with JPEG, PNG, and WebP support.
* Optional WooCommerce Product mappings for price, regular/sale price, SKU, stock status, and the first gallery image.
* Site defaults, content-type defaults, taxonomy/term rules, and per-item Inherit, Custom, or Disabled configuration.
* A visual picker for your saved SocialCards templates.
* Private Preview of current editor values without creating a Media Library attachment.
* Manual Generate image, Update image, and Refresh image actions for saved eligible content.
* Opt-in automatic generation through WP-Cron after published content is saved.
* Bulk Generate / update and Refresh images actions, with generation progress.
* An Images dashboard with Current, Outdated, and Missing status workflows, plus failure and job status feedback.
* Image-only integrations with SEOPress, Rank Math, and Yoast SEO, or standalone social metadata output.

Generated images do not replace the Featured image. Normal generation reuses an unchanged image; Refresh image or Refresh images forces a render. Changing defaults or rules does not immediately regenerate existing images: review affected items in Images and use Generate / update.

== External services ==

SocialCards relies on the external service at [social.cards](https://social.cards/). The plugin contacts this service only after an API key is configured. API keys are available with SocialCards Pro. The configured API key authenticates server-side requests and is not exposed in browser settings or thumbnail URLs.

= Account connection =

Check connection contacts SocialCards to verify account/API access and retrieve account identity and access capabilities. Saving an API key alone does not check the connection.

= Templates =

When connected, template selection, refresh, and related admin/editor workflows retrieve the account's owned saved template metadata, variables, revisions, and private template thumbnails. Connected admin screens may also refresh template revision information. These requests send authentication, template identifiers, and pagination values as needed.

= Preview and rendering =

Preview, manual generation, bulk generation, and opted-in automatic generation send the selected template identifier and configured values needed to render that template.

Mapped text may include post/page titles, excerpts, author display names, publication dates, site names, custom text, and WooCommerce product values such as prices, SKU, and stock status. Mapped images may include local Featured images and WooCommerce gallery images. JPEG, PNG, and WebP image bytes and their MIME types may be transmitted privately to SocialCards for rendering; mapped image values are not WordPress media URLs or filesystem paths.

Standard HTTP metadata, such as the WordPress server's IP address and WordPress HTTP User-Agent, may also be visible to the service. The default User-Agent may include the site's URL and WordPress version.

Normal public frontend page requests do not call the SocialCards API. Previously authorized generation jobs run separately through WP-Cron. Rendered final PNG images generated through this integration are saved in the site's WordPress Media Library. Preview responses do not create an attachment.

Processing and retention by the SocialCards service are governed by the [SocialCards Privacy Policy](https://social.cards/privacy-policy) and [Terms of Service](https://social.cards/terms-of-service).

== Installation ==

1. Install and activate SocialCards.
2. Obtain an API key from a SocialCards Pro account.
3. Open SocialCards > Settings, enter the key, and select Save token, then Check connection.
4. Choose templates and mappings under Defaults & Rules or for an individual content item.
5. Use Preview to inspect current editor values. Save eligible content before Generate image or Update image.
6. Select a social metadata mode in Settings if you want SocialCards images supplied to social metadata.
7. Optionally enable Automatic generation. Use Images for bulk Generate / update or Refresh images.

== Frequently Asked Questions ==

= Does SocialCards require a SocialCards account? =

You can install the plugin without a connection. Connecting, saved-template access, Preview/rendering, automatic generation, and bulk generation require a SocialCards Pro account and API key. Rendering is provided by the external service, not a local WordPress image generator.

= Where are generated images stored? =

Final generated PNGs are normal WordPress Media Library attachments. They do not replace your Featured image.

= What content can receive a final SocialCards image? =

Content must be published, publicly viewable, not password-protected, and belong to a supported/enabled content type. An effective SocialCards template is required. Drafts and private content can use authorized private Preview where available, but final persistent generation is limited to eligible public content. Private content is excluded from the Images management list.

= Does Preview create a Media Library image? =

No. Preview is private and does not create an attachment or publish social metadata. It sends the mapped editor values to SocialCards for rendering.

= Which source image formats are supported? =

Mapped image variables support local JPEG, PNG, and WebP uploads. Final generated SocialCards images are PNG. GIF, SVG, AVIF, and offloaded images without eligible local upload bytes are not supported for image-variable mapping.

= Which SEO plugins are supported? =

SocialCards provides image-only integrations with SEOPress, Rank Math, and Yoast SEO. Those plugins retain control of their other metadata. Manual social images configured in the selected SEO plugin take priority. SEOPress requires its Social module and corresponding social output to be enabled.

Standalone mode can output Open Graph and Twitter metadata when no supported SEO plugin is detected. Select one mode in Settings. Conflicting supported SEO providers suppress SocialCards image overrides and standalone fallback.

= What happens if I disconnect SocialCards? =

API-dependent actions become unavailable. Saved WordPress configuration and generated Media Library images are preserved. Reconnecting with a valid API key and current access restores API functionality. Disconnect removes the local key and cached connection data; it does not revoke the key at SocialCards.

= What happens if I deactivate or delete the plugin? =

Deactivation clears pending SocialCards generation events and ephemeral runtime state, including active progress, locks, and caches. It preserves settings, the API key, configuration, generated-image references, and Media Library images.

Version 0.1.0 has no destructive uninstall cleanup. Deleting the plugin leaves WordPress-stored SocialCards configuration and generated Media in place; remove unwanted retained data separately.

== Screenshots ==

1. Images dashboard with freshness/status feedback and generation controls.
2. Defaults & Rules with reusable template configuration and taxonomy rules.
3. Gutenberg SocialCards sidebar with the current image and Preview controls.
4. Visual template picker displaying saved SocialCards templates.
5. WooCommerce Product text and image mappings.

== Changelog ==

= 0.1.0 =

* Initial release with template mappings, site/content-type defaults, and taxonomy rules.
* Private Preview, manual generation, opt-in automatic generation, and bulk generation.
* Generated PNG storage in the WordPress Media Library and image freshness/status feedback.
* Optional WooCommerce Product mappings.
* SEOPress, Rank Math, and Yoast SEO image integrations and standalone social metadata mode.
