This is a short technical introduction to outline how a game or app might integrate with the Playmob platform. Our API requires only a single HTTPS call to be made. It works alongside your existing in­-game store, purchase providers and account system, making it completely platform agnostic.

Terminology

Playmob’s API allows you to record purchases of in-app items as part of your campaign. In our API we call an in-app item a user action and a purchase a user event.

One or more user actions are part of a Playmob campaign which are run by a specific developer for a certain time period. Campaigns contribute money to a specific project by a charity.

Each title gets a public page on playmob.com (sample).

Technical Integration Process

Reporting user events (purchases) to Playmob is done transparently by your game, without requiring any UI or explicit user interaction:

  1. Playmob will provide access to a developer portal where titles and user actions (items) can be added and edited. Your API credentials and other IDs that the API call requires can be obtained on the ‘Help’ tab of your corresponding campaign of the developer portal. Content for your public title page is also configured there.
  2. During your purchase process, call our API and pass in the user action ID (see the Purchase API Call Reference section for details). Playmob makes no assumptions about how you call our API and we don’t require you to use any specific native API wrapper. Simply perform an HTTPS POST request to Playmob’s API.
  3. Calls are signed to confirm the integrity of the data submitted.
  4. The Playmob API takes the transaction receipt information obtained from your payment platform (Apple, Google) and our backend will certify that a reported purchase is a valid one. Thus, it is safe to embed your API call code straight into your game client. For iOS titles, send a a base64 encoded string of the transaction details (See the section on ‘Validating Receipts With the App Store’ section of Apple’s documentation). Android titles should use the signed data INAPP_PURCHASE_DATA returned from a transaction as a plaintext JSON string. Your title will need to be set up to perform purchase verification first.
  5. Once you’ve begun to report user events to the Playmob API, the developer portal will reflect them in a debug log under the User Events tab of your campaign for confirmation.

After you’ve confirmed that user events are reporting properly to Playmob, we’ll work with your marketing/PR contacts to plan your campaign launch.

User Event API Call Reference

To record a single user event, make a POST request with JSON data to https://api.playmob.io/api/v5/user_actions/:user_action_id/user_events.json (replace ‘:user_action_id’ with your user action ID).

API requests must be signed to be accepted.

A successful request will return a numeric user_event_id as part of the response.

For the full parameter list that this API call accepts, see this list.

Tagged: