Playgama MCP - Publish & Manage HTML5 Games

Apply a developer-provided referral code or invitation URL to this organization before its first-ever Sandbox publication. Never invent a code. One inviter per organization; the attribution cannot be changed and self-invitations are refused. Grants one traffic welcome bonus without starting a campaign. Repeating the same invitation returns ALREADY_APPLIED and the same bonus, including after a lost answer. A different invitation cannot replace it. Read get_referral_program to recover state after an uncertain result.

Step 3 of 3, after the PUT: adds the archive to the game’s form (earlier archives stay) and queues unpacking and the Bridge SDK analysis. Successful unpacking makes the game files available at a public archive URL for QA; this does not publish the sandbox page or catalog listing. Refused with 409 while nothing is uploaded. Safe to repeat. Answers the get_archive_status view; keep polling that tool.

Step 3 of 3, after the PUT: checks the file (the started format, the exact slot size, a complete image), publishes it and puts it into its slot; replaced names the cover taken out. Refused with 409 while nothing is uploaded, 422 when the file does not fit (the reason is given; start a new upload), 502 when it could not be published (not confirmed). Safe to repeat.

Create a draft game. Answers its id, which the other tools take. Titles are not unique: if a call failed without a clear answer, check list_applications before creating again.

Add a leaderboard to a game. id is its Bridge SDK tag: unique within the game and not changeable later. Check list_leaderboards for tags already taken. Deleting a leaderboard is not available.

The saved form of one game, with the metadata of its archives and media. No file contents or download links.

A link that opens an unpacked archive (processing DONE) in the Playgama QA Tool, where a human plays it and submits it to moderation. mode: certification opens the certification page, whose Build Startup section shows why the Bridge SDK did not initialize — get_bridge_sdk_docs has the integration docs; it unlocks nothing. Also answers processing, failedAt and bridgeSdk.

The state of one archive. state.status: CHECKING while the build check runs, then PASSED, PROBLEM or NOT_CHECKED. Poll until it is no longer CHECKING; on PROBLEM or NOT_CHECKED give the developer state.message word for word — it names what is wrong and what to do — and take state.reason as its code (get_bridge_sdk_docs has the SDK integration docs; get_archive_qa_tool_link with mode: certification shows the startup log). processing: PENDING (unconfirmed or unpacking), DONE (unpacked), FAILED with failedAt: UNPACK and errorMessage (upload a corrected zip). bridgeSdk: whether that same check found the Playgama Bridge SDK in the build — FOUND, NOT_FOUND, or PENDING while it has not answered. analysis: what the check measured — bridgeVersion and bridgeEngine, null when no check has run. Publishing and submitting are decided by state.

The live Playgama Bridge SDK wiki. Start with page: api: its Required steps are mandatory for every game — read them when you start work on a game and before integrating the SDK, and again when an archive answered bridgeSdk: NOT_FOUND. Without page: the index, one { page, title, required, description? } per page. With page (an id from the index, e.g. "api/storage"): that page’s title, url and markdown, cut to engine’s tabs when the page has tabs and one matches — engineFilter says which tabs existed and which were kept. An unknown page is refused with the list of valid ids. The rules the whole game must meet are get_game_checklist; recommendations are get_game_guides.

The values update_application_form takes for category, in priority order, and how to choose one. Read it before setting or changing a game’s category. howToChoose is the rule; each of categories has slug (what the form takes), title, description, like (the kinds of games it holds), examples (names of Playgama games of it) and notLike: games it does not hold, each with the categories they belong to. groups is how the console groups them. The same list the console shows the developer.

Every numbered rule a game and its build archive must meet to go up on Playgama, read live from the Game Requirements section of the Playgama wiki. Read it together with the Required steps of the Bridge SDK (get_bridge_sdk_docs, page: api) when you start work on a game, before writing code (layout, sound, saving and ads are decided in the first build), and again before every start_archive_upload: check the game and the archive against each item by its number, fix what fails before uploading, and tell the developer which numbers you could not check yourself. If the requirements cannot be read, say so: never report the archive as checked. Without page: { title, url, markdown, pages, requirements, unavailable } — the index; every requirement page as { page, title, required, description? }, all required; the markdown of every page but the platform-specific requirements as { page, title, url, markdown }; and { page, title } of the pages that could not be read right now — tell the developer their rules were not checked. The platform-specific requirements apply to the partner platforms the game is distributed to: read them by page. With page (an id from pages): that page’s title, url and markdown. A Bridge SDK link inside goes to get_bridge_sdk_docs and a guide link to get_game_guides, as their page, as written.

Recommendations for building, monetizing and optimizing a game for Playgama, read live from the Playgama wiki: loading and the first session, responsive layout, controls, sound, saving progress, ad and purchase design, performance. Moderation checks none of it — the rules are get_game_checklist — so a guide is never a reason to block an upload. Read the guide that matches the work at hand: layout, sound or controls while building the game, monetization while placing ads and purchases, performance while optimizing. Without page: { title, url, markdown, pages } — the index and one { page, title, required, description? } per guide. With page (an id from pages): that guide’s title, url and markdown. A Bridge SDK link inside goes to get_bridge_sdk_docs and a requirements link to get_game_checklist, as their page, as written.

Compact overview of one game’s preaggregated telemetry: volume, event inventory, sessions, users, duration and freshness. Start here, then call the event, timeseries or session-facts tool only for the question you need to answer. The JSON is dynamic: inspect schema_version, period, freshness, sample sizes and every returned field; unknown fields may be added, and missing or null never means zero. dateFrom and dateTo are inclusive calendar dates and may span at most 31 days. The event inventory defaults to 50 types and is capped at 100. Follow events_page.next_cursor with eventCursor only when more event types are needed for the current question; do not fetch every page preemptively. The tool returns evidence, not a server-generated conclusion. Read get_game_telemetry_guide before instrumenting a game or interpreting this response.

Preaggregated detail for one event. Call without fieldName to discover every top-level custom field and its type, coverage, cardinality and numeric or boolean summary. Call again with one fieldName to obtain its bounded top categorical JSON values and other_event_count. Nested objects and arrays are dynamic JSON values, not a fixed DTO. For performance_sample, use this tool to read the available FPS, frame-time and stutter field summaries for the requested period. Use event names discovered in get_game_telemetry_analytics; do not request raw events.

Agent-only instructions for instrumenting a Playgama game and interpreting its telemetry. Read before finishing a game: it defines the performance_sample contract, how to choose bounded product progression events, the temporary custom-to-system event migration, privacy rules, and how to drill down through the compact telemetry analytics tools without requesting raw or unnecessarily large datasets.

Paginated, preaggregated and pseudonymized session facts for sequence questions such as whether a player found an item before dying or restarted after defeat. At least one of eventName, fieldName, sessionRef or userRef is required. Start with the default 20-session page and fetch another page only when the current question needs it. Facts contain dynamic sanitized JSON in ordered chunks; they are not raw events and must not be treated as a complete user history. Repetitive core_ping and performance_sample events are intentionally excluded: never filter session facts by either name or use this tool for per-session FPS analysis.

Paginated preaggregated 30-minute or daily telemetry counts for trend, release and regression comparisons. Optionally narrow by event namespace and event name. Follow page.next_cursor only while more points are needed for the current conclusion; the response also returns the applied limit. Points describe event volume and coverage, not FPS or other custom-field value distributions. Compare performance values with bounded event-analytics requests instead. This tool never reads or returns raw events.

The developer’s path for the game, step by step in the order it is walked, judged by the latest archive (archiveId): the steps the tools of this connection can move. Each step: id, state (TODO, IN_PROGRESS, DONE, FAILED, BLOCKED, UNKNOWN, PARTIAL, OUTDATED, AVAILABLE, WAITING, CABINET), reason, required, nextTools, blockedBy and askDeveloper. current is the first required step still holding the path, null when none is. UNKNOWN is neither done nor not done: call again. CABINET: what is left is the developer’s, in the console.

A link that opens the Playgama QA Tool on a game you serve yourself (e.g. on localhost), to play it in the Bridge SDK harness before uploading. Leave sessionId out for a fresh environment; reuse one to keep saved state.

The game’s latest publication on each destination, newest first. A destination with no publication on record is absent, which does not mean never published: what each destination serves is get_application activeArchives. platform is PLAYGAMA_SANDBOX — the sandbox, published by publish_sandbox — or PLAYGAMA — the catalog, published by send_playgama_catalog_update or from the console. Each has id, releaseId, archive (null only once that archive is gone), startedAt, updatedAt and status — IN_PROGRESS while its archive is built and published, PUBLISHED once its build went live, FAILED when it never did, with no reason given — and retryAfterSeconds, the wait before reading again while IN_PROGRESS, null otherwise. After a publish, read it again at that pace until it leaves IN_PROGRESS; on FAILED tell the developer, a new publish starts over. What the sandbox serves now is always get_sandbox_state site.revision. A publish with no answer may still land after any read, so never tell the developer it did not: compare with the publication read before the call — a new releaseId naming this archive is a publication of this archive, that call’s or another’s: follow it; otherwise the outcome is unknown: say so — another publish is a new request, on a new yes.

Read the current organization’s stable invitation code/link, eligibility, aggregate invitation counts and available traffic bonuses. There is no enrollment step. Every organization member can read the invitation; share the returned invitation.url. Each accepted invitation grants the invited organization a traffic welcome bonus; its first successful Sandbox publication grants the inviter another traffic bonus. These are not cash or guaranteed player counts. An existing organization can accept an invitation until its first-ever Sandbox publication. A referral bonus needs no social post and does not use the share bonus allowance, but shares the active-campaign capacity. To use a bonus, choose a game, read get_sandbox_traffic, ask the developer, and call start_sandbox_traffic with bonusId instead of postUrls. Merely reading or applying a code does not start traffic.

The ready post (share.text) and share links (share.links) for the game’s live sandbox. share is null when the sandbox is not published or is blocked. Facebook takes only the link — the developer pastes share.text.

The game’s sandbox — a public page anyone with the link can play: site (link, status, live revision), or null if never published — a sandbox Playgama blocked is shown with status BLOCKED even then; what is live now is always site.revision, and how a publish request went is get_publications. With archiveId it adds publish: allowed, reason, message and the refusal’s own fields (failedAt, details, emptySlots, limit/used/resetsAt) — the refusal publish_sandbox would give, in the same words — changeStatus (CHANGED: this archive or the form differs from the live revision; UNCHANGED: they match, and a publish still builds and publishes them again as a new revision; UNKNOWN: cannot tell; none of them refuses) and archiveChanged.

Read campaign eligibility, bonus offers and existing traffic runs for this game. This read does not launch a campaign or spend a traffic bonus. verdict and offer describe the share bonus, referralOffer a referral bonus (get_referral_program) with its bonusId when available. verdict.reason when not allowed: DSP_DISABLED, NO_SITE (publish first), BLOCKED, NO_COVERS (upload covers, publish again), ANALYSIS_PENDING (ask again shortly), NO_BRIDGE (Bridge SDK not detected; get_bridge_sdk_docs has the integration docs), RUN_IN_PROGRESS, PAYMENT_REQUIRED (share bonus used; paid traffic is in the console), ORG_LIMIT (three share bonuses per organization, lifetime; legacy free runs do not count). offer: FREE or PAID, available (the free bonus only), remainingFreeRuns, durationDays (one free boost), budgetUsd (per post, internal accounting — present a free boost without a dollar amount). current: the run in progress (PENDING, then RUNNING); runs: newest first, with status, failureReason and postUrls. After a start, find the returned run.id in runs and poll until it leaves PENDING. In get_launch_steps the traffic step names its source: REFERRAL with a bonusId (get_referral_program) or SHARE; any completed traffic campaign closes that step, and further bonuses do not reopen it.

Whether the game can be submitted to moderation now and, if not, why — the first rule the submit itself would refuse with. reason, in that order: ORGANIZATION_BANNED, MODERATION_UNAVAILABLE (the game cannot go to moderation, catalogAvailable is false: publish it to the sandbox), missing certification, a cooldown after a failed moderation, the state of the build being submitted (ARCHIVE_PENDING, ARCHIVE_FAILED, ARCHIVE_CHECKING while its check is still running, or the archive’s own reason code — get_archive_status explains it), ARCHIVE_NOT_BUILDABLE (the build has no Bridge version or Bridge config to build with: integrate the Bridge SDK and upload it again), FORM_INCOMPLETE (details names the fields to fill or fix, the title included: empty or with non-Latin letters), COVERS_INCOMPLETE (not all three covers are in place: upload the ones emptySlots names), or nothing changed since the last submit. message is the console’s wording of that refusal. Name in archiveId the build you are asking about — the one a submit would freeze. While catalogAvailable is false the answer is always MODERATION_UNAVAILABLE, whatever the build: never tell the developer the game can be submitted. A game never submitted to moderation, or one moderation rejected or postponed, whose sandbox is not blocked (get_sandbox_state), opens once its sandbox reaches the targets shown on its sandbox card in the console — the play time among them is set by the game’s category — counted once a day. A game moderation took off, or whose sandbox is blocked, only Playgama can reopen: the sandbox targets do not. A game Playgama restricted stays closed whatever its targets and track, until Playgama lifts the restriction. A human submits to moderation in the console. With reviewType AUTO the verdict is send_playgama_catalog_update’s: the same reasons, then AUTO_REVIEW_UNAVAILABLE — the game is not live in the Playgama catalog (autoReviewPlatforms is empty), so only moderation can take it.

Every named game of your organization, newest first: id, title, status and last update. The order is stable, so paging visits each game once. Untitled and deleted games are not listed. There are no filters: match on title or status yourself.

The saved in-app catalog of a game and its checksum. Pass the checksum to replace_in_app_products as expectedChecksum.

The leaderboards of a game. id is the tag the game passes to the Playgama Bridge SDK and the one update_leaderboard takes; rows also carry name, type, scoreOrder, decimals, isActive and read-only score-protection settings.

The moderation correspondence on a game, newest first, grouped by moderation task. Read-only.

Publish this archive to the game’s sandbox — a public page anyone with the link can play, without moderation. Ask the developer first. Before calling, read get_sandbox_state with the same archiveId: its publish says whether this call would be refused, in the same words. A publish needs the build check PASSED (get_archive_status state), Playgama Bridge 2.2.0 or newer in the build, all three covers and a complete form. Answers outcome PENDING: the archive is built, then published, as a rule within minutes; url is the sandbox’s link, revision what is live until then (null before the first publication). Follow its PLAYGAMA_SANDBOX publication in get_publications; once PUBLISHED, hand out url and offer the post and links of get_sandbox_share. Until it ends, another publish is refused with 409: wait and call again. Refusals (reason): ARCHIVE_PENDING — if get_archive_status already says DONE, upload again; PUBLISHED_ON_PLAYGAMA — the game is live in the catalog, its sandbox is closed for good; BLOCKED — Playgama blocked this sandbox, a publish cannot lift it; RATE_LIMITED — 15 publications per rolling hour, repeats included: wait; ORG_QUOTA — wait until resetsAt, do not retry. The rest name what to fix: the build check’s own reasons (get_bridge_sdk_docs has the SDK docs), ARCHIVE_FAILED, BRIDGE_VERSION_OUTDATED, BRIDGE_VERSION_UNKNOWN, FORM_INCOMPLETE (details: the fields to fill or fix, the title included: empty or with non-Latin letters), COVERS_INCOMPLETE (emptySlots).

Replace the whole in-app catalog with products — not a patch: a product you leave out is deleted, and an empty list clears the catalog. Ask the developer before removing products. Read list_in_app_products first and pass its checksum as expectedChecksum; if the catalog changed meanwhile, the call is refused. While in-game purchases are off, a call that leaves them off is refused (IN_GAME_PURCHASES_OFF): turn them on with hasInGamePurchases: true to change the catalog.

Send this archive and the saved form to the Playgama catalog as an update of the game live there, without moderation: once it is published, every catalog player gets it and no moderator checks it first. Write updateNote — what players will notice in this update — every time; a refused note writes nothing: fix it and call again. Call it only on the developer’s explicit yes in this conversation: first tell them the game, the archive and that the game live in the Playgama catalog will be updated for all its players with no moderation; a yes to an earlier update or to a sandbox publish does not count. Before asking, read get_submission_state with this archiveId and reviewType AUTO: it says whether this call would be refused, in the same words. Only a game live in the catalog takes it (autoReviewPlatforms holds PLAYGAMA); a first publication and every other platform go to moderation, which a human submits in the console. Answers outcome PENDING and releaseId: follow that PLAYGAMA publication in get_publications, read before the call too. On FAILED players keep the previous build. Until it ends, another publication of the game, to the catalog or the sandbox, is refused with 409 PUBLICATION_IN_PROGRESS. Never call again on an old yes: the form goes as it is when the call goes in, so another call is a new update, after get_submission_state and a new yes. Refusals (reason): AUTO_REVIEW_UNAVAILABLE — not live in the catalog; NO_CHANGES — the archive and the form are those of the last submit; PUBLICATION_IN_PROGRESS; and every reason get_submission_state names.

Step 1 of 3 of uploading a build: a zip that meets the game requirements — read them with get_game_checklist and check the build against each item first. Answers uploadUrl and headers: PUT the zip there with exactly those headers within an hour, e.g. curl -T game.zip -H "Content-Type: application/zip" "<uploadUrl>", then call confirm_archive_upload.

Step 1 of 3 of uploading one cover. Answers uploadUrl and headers: PUT the file there with exactly those headers within an hour, e.g. curl -T cover.png -H "Content-Type: image/png" "<uploadUrl>", then call confirm_cover_upload.

Start an ad campaign that sends players to the sandbox page. Send exactly one of bonusId or postUrls. A referral bonusId (get_referral_program) needs no social post; a timeout is not permission to spend another bonus. The separate share traffic bonus: first help the developer post the game (get_sandbox_share has the post and links), then ask the developer to paste the links of their published posts and pass 1–2 of them (different public HTTPS links from any platform) — never invent one. Each accepted link adds one boost unit to the campaign, up to two. One campaign per game, three games per organization for its lifetime; earlier free runs without sharing do not count. No dollar amount. Ask the developer first. Needs covers in the published revision and the Bridge SDK. Answers the PENDING run; poll get_sandbox_traffic for the returned run.id until it leaves PENDING — FAILED carries failureReason. Only a confirmed safe failure makes a referral bonus retryable; an uncertain DSP outcome keeps its reservation. A refusal carries the reason get_sandbox_traffic shows, or SHARE_REQUIRED / INVALID_POST_URL for missing or invalid links; PAYMENT_REQUIRED: paid traffic is in the console. Repeatedly submitting already accepted links reuses the same grant without changing its budget or dates. Add the remaining link later (up to two total) to increase the same campaign budget and extend it to at least three days from submission, including after it has finished. New links wait while a launch/update is PENDING (RUN_IN_PROGRESS).

Save form fields of a game. Partial save: a field you leave out keeps its value; enum arrays are replaced whole. Does not submit anything to moderation.

Change the name, type or score order of a leaderboard; at least one is required. The tag cannot change, and deleting is not available.