=== JournaPlay ===
Contributors: journaplay
Tags: games, quiz, news, engagement, embed
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn news articles into interactive games. Embed JournaPlay games with a block or shortcode, or generate them automatically when a post is published.

== Description ==

[JournaPlay](https://journaplay.com) turns a news article into interactive games — an article quiz, word search, timeline, sliding puzzle, connection web, lie detector and "The Journalist" investigation game — that readers play right inside the article.

This plugin connects your WordPress site to JournaPlay:

* **JournaPlay Game block** — add the block (Embeds category), paste the game ID from JournaPlay Studio and you are done. Choose between a single game or all games of one article shown as tabs.
* **Shortcode** — `[journaplay id="abc123"]` for a single game, `[journaplay group="xyz789"]` for all games of an article. Works in the classic editor, widgets and page builders.
* **Auto-generate on publish** *(Enterprise plan)* — with an API key, the plugin can create a game from the post title and text the moment a post is published, link it to the post and, if you like, insert it automatically at the end of the content.
* **JournaPlay box on the edit screen** — see the linked game, preview it, copy its shortcode, generate a game on demand ("Generate now") or unlink it.
* **Test connection** button to verify your API key and see your organisation, plan and monthly quota.

Games are loaded from JournaPlay's servers in an iframe that fits the width of your article; nothing heavy is added to your site.

= Which plan do I need? =

Embedding games works on **every** JournaPlay plan: publish a game in JournaPlay Studio, copy its ID and paste it into the block or shortcode.

Automatic generation from WordPress (the "Auto-generate" option and the "Generate now" button) uses the JournaPlay public API, which is available on the **Enterprise** plan. Create an API key in JournaPlay Studio → Settings → API keys and paste it under Settings → JournaPlay.

= Privacy =

The plugin only talks to the server configured under Settings → JournaPlay (by default https://journaplay.com). When auto-generation is used, the title and plain text of the published post are sent to that server to build the game. Readers' browsers load the game player from the same server. No other external requests are made.

= For developers =

* Hooks: `journaplay_embed_html` (filter the embed markup), `journaplay_should_auto_generate` (skip generation for a post), `journaplay_game_lang` (language code sent to the API), `journaplay_article_text` and `journaplay_max_text_length` (text sent to the API), `journaplay_game_generated` (action after a game is linked).
* Post meta: `_journaplay_game_id`, `_journaplay_game_type`, `_journaplay_play_url`, `_journaplay_last_error`.
* Options: a single array option `journaplay_settings`.

== Installation ==

1. Upload the `journaplay` folder to `/wp-content/plugins/`, or upload the zip under Plugins → Add New → Upload Plugin.
2. Activate the plugin through the Plugins screen.
3. Go to Settings → JournaPlay. Leave the server URL as is unless you host JournaPlay yourself.
4. *(Optional, Enterprise)* Paste your API key, click "Test connection", then enable "Auto-generate a game when a post is published" and, if wanted, "Insert the game automatically at the end of the post content". Tick the post types it should apply to.
5. To embed a game manually, add the "JournaPlay Game" block or the `[journaplay id="..."]` shortcode to a post.

== Frequently Asked Questions ==

= Where do I find the game ID? =

In JournaPlay Studio, open the game and click Publish. The embed code contains the ID: `<script src="https://journaplay.com/embed.js" data-id="abc123" async>` — the ID is `abc123`. The block also accepts the whole embed snippet or the player URL and extracts the ID for you.

= What is the difference between a game ID and a group ID? =

A game ID shows one game. A group ID shows every game that was generated from the same article, with tabs to switch between them. Studio shows both codes on the Publish screen.

= Do I need an API key to embed games? =

No. The API key is only used to generate games from WordPress automatically. Embedding by ID works on any plan.

= Auto-generation does not create a game. Why? =

Check, in this order: the API key is set and "Test connection" succeeds; "Auto-generate" is enabled; the post type is ticked under "Post types to apply to"; the post did not already have a linked game (posts are only processed the first time they are published). If the API call failed, the reason is shown in a notice on the post edit screen and in the JournaPlay box. Common causes: an invalid key (401), a plan without API access or an exhausted monthly quota (402), or the rate limit (429).

= Can I create all game types at once? =

Not through auto-generation yet: one API call creates one game of one type, so the plugin creates a game of the default type chosen in the settings. To offer all games of an article as tabs, generate them in JournaPlay Studio and embed the group ID.

= Will the game be inserted twice if I also add the block? =

No. Auto-insert is skipped when the content already contains a JournaPlay block or shortcode.

= Which language is used for generated games? =

The two-letter language of your site (Settings → General → Site Language), e.g. `tr` for Turkish. Use the `journaplay_game_lang` filter to change it.

= What happens when I uninstall the plugin? =

The plugin options are deleted. The post meta that links posts to their games (`_journaplay_game_id`, `_journaplay_game_type`, `_journaplay_play_url`, `_journaplay_last_error`) is kept on purpose, so if you reinstall the plugin your posts keep their games. Games themselves live in JournaPlay and are never deleted by this plugin.

== Screenshots ==

1. Settings → JournaPlay with the "Test connection" button.
2. The JournaPlay Game block in the editor.
3. The JournaPlay box on the post edit screen.

== Changelog ==

= 1.0.0 =
* Initial release: block, shortcode, auto-generate on publish, auto-insert, meta box with Generate now / Unlink, settings page with Test connection.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
