Integration guide for API

Monetizr integration via API

About API integration

This is a frontend forcing API for integration with your game, it does not hold any GDPR compliant data and all data that are exposed are public. We are using per developer, per application generated oAuth access tokens with limited access, to remove privacy and data leakage concerns from early on. We are open for a discussions for more privacy and security, reach out to mj@monetizr.io if you have concerns or suggestions.

For client purposes we have created RESTful API based on JSON data structure (web service on representational state transfer (REST) technology), an architectural style and approach to communications in web services development. JavaScript Object Notation (JSON), an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types.


API allows its users and developers to integrate with Monetizr middleware the way they appreciate the most - fully configurable with open-ended use cases. Only the developers themselves know how they want to implement functionality and RESTful API is the way they have control on their end. If you as a developer spot anything that you want for us to develop, change or improve, then please, give us a feedback and we are going to create a plan for implementation.

As of this moment, the API presented here and its reference guide is available at https://api3.themonetizr.com/docs/ We are constantly working on our API, better suited data-types, performance, evaluating our exposure to outside and creating API endpoints that are easy to use and understand.

The minimum requirements to start using Monetizr API is:

  • reach out to Monetizr to acquire authorization access token for your products (generated 256-bit key), this key allows to access your publicly available, custom designed merchandise products
  • if you, as a developer, wish to implement access token grant on your application, Monetizr provides you with client credentials and you can implement oAuth authorization requests on application side. For the simplicity, as this front facing API does not grant access to any private information, Monetizr generates access tokens. We advice you to implement access token grants on your application, but do not prompt on it as it is your own decision
  • work with Monetizr design and implementation team, who will help you to create merchandise as a main game reward with the help of octalysis framework. Monetizr team then will take care of merchandise related processes: design, delivery, payments and support
  • if you wish to use your own tags for merchandise to better understand game-play, then in the process of designing game rewards provide Monetizr team with a list of tags (Tag can be an identifier for the product e.g. “tshirt_1”, “menu_button”, “level2_unlocked”, “challenge_1_completed”
  • start using API, see technical implementation, and create your own unique in-game rewarding experience, as API is communications channel and does not interfere with your game design
  • if you are willing to better understand your players, then we welcome you to integrate not only minimum requirements, but gather extra data, and Monetizr will use advanced automated learning techniques to provide behavioral analysis of your game players (this is not required to start using our rewarding, but we suggest you to consider understanding your clients better)
  • Monetizr already analyses sales data (game rewarding data) and provides our customers with useful financial analysis

The minimum steps to start using Monetizr reward engine by integrating with our API:

Preparations

Manual step: acquire access token and receive Monetizr designed rewarding merchandise tags

Integrate Monetizr API (every request has to have Authorization header):

Authorization Bearer <your-access-token>

Make a request to get your merchandise information

Authorization Bearer <your-access-token>

curl -H "Authorization: Bearer 4D2E54389EB489966658DDD83E2D1" https://api3.themonetizr.com/api/products/tag/30-credits

curl -H "Authorization: Bearer 4D2E54389EB489966658DDD83E2D1" https://api3.themonetizr.com/api/products/tag/monetizr-sample-t-shirt

curl -H "Authorization: Bearer 4D2E54389EB489966658DDD83E2D1" https://api3.themonetizr.com/api/products/1794883780674

Example token, can be used for testing: 4D2E54389EB489966658DDD83E2D1

Example merchandise id: 1794883780674

Example merchandise tag: 30-credits or monetizr-sample-t-shirt


The response will be json content holding parameters, you can create your own custom representation to match your game:

  • id: Merchandise id that is used to add it to the cart
  • title: Merchandise title as it is specified in Monetizr online shops
  • description: Product description to show for end-users
  • descriptionHtml: Not advised but product description with related html tags
  • availableForSale: Boolean value to determine if product is available
  • onlineStoreUrl: Products location in online store
  • images: Images related for specified product
  • variants: Available variants, for example, if merchandise is t-shirt, this object contains available shirt sizes, titles and prices for each item
{
  "data": {
      "productByHandle": {
          "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzE3OTQ4ODM3ODA2NzQ=",
          "title": "1 ticket unlocked. Redeem now!",
          "description": "🏀 Basketball run giveaway! Prizes include 🎁 20x Amazon.com $5 Gift Card*, 🎽 3x Official March Madness T-shirts, 👕 1x Limited edition Basketball run T-shirt by Playvue. You have 1 ticket, click the \"Claim\" button below to redeem your ticket. Enter multiple times to increase your chances! 🗓 Lucky winners will be chosen via raffle on April 23, 2019. Winners will be announced in the game, on Playvue Facebook page and informed individually. *Restrictions apply, see amazon.com/gc-legal",
          "descriptionHtml": "<p>🏀 <strong>Basketball run giveaway!</strong> Prizes include 🎁 <strong>20x</strong> Amazon.com $5 Gift Card*, 🎽 <strong>3x</strong> Official March Madness T-shirts, 👕 <strong>1x</strong> Limited edition Basketball run T-shirt by Playvue.</p>\n<p>You have 1 ticket, click the \"<strong>Claim</strong>\" button below to redeem your ticket. Enter multiple times to increase your chances!</p>\n<p>🗓 <strong>Lucky winners will be chosen via raffle on April 23, 2019</strong>. Winners will be announced in the game, on Playvue Facebook page and informed individually.</p>\n<p>*Restrictions apply, see <a href=\"https://www.amazon.com/gc-legal\" target=\"_blank\" rel=\"noopener noreferrer\">amazon.com/gc-legal</a></p>",
          "availableForSale": true,
          "onlineStoreUrl": "https://shop.themonetizr.com/products/1794883780674",
          "images": {

          },
          "variants": {
              "edges": [
                  {
                      "node": {
                          "id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8xNDk3MjcyNzg4NTg5MA==",
                          "product": {
                              "title": "1 ticket unlocked. Redeem now!",
                              "description": "🏀 Basketball run giveaway! Prizes include 🎁 20x Amazon.com $5 Gift Card*, 🎽 3x Official March Madness T-shirts, 👕 1x Limited edition Basketball run T-shirt by Playvue. You have 1 ticket, click the \"Claim\" button below to redeem your ticket. Enter multiple times to increase your chances! 🗓 Lucky winners will be chosen via raffle on April 23, 2019. Winners will be announced in the game, on Playvue Facebook page and informed individually. *Restrictions apply, see amazon.com/gc-legal",
                              "descriptionHtml": "<p>🏀 <strong>Basketball run giveaway!</strong> Prizes include 🎁 <strong>20x</strong> Amazon.com $5 Gift Card*, 🎽 <strong>3x</strong> Official March Madness T-shirts, 👕 <strong>1x</strong> Limited edition Basketball run T-shirt by Playvue.</p>\n<p>You have 1 ticket, click the \"<strong>Claim</strong>\" button below to redeem your ticket. Enter multiple times to increase your chances!</p>\n<p>🗓 <strong>Lucky winners will be chosen via raffle on April 23, 2019</strong>. Winners will be announced in the game, on Playvue Facebook page and informed individually.</p>\n<p>*Restrictions apply, see <a href=\"https://www.amazon.com/gc-legal\" target=\"_blank\" rel=\"noopener noreferrer\">amazon.com/gc-legal</a></p>"
                          },
                          "title": "Default Title",
                          "priceV2": {
                              "currencyCode": "USD",
                              "amount": "0.0"
                          },
                          "image": {
                              "transformedSrc": "https://cdn.shopify.com/s/files/1/1133/5330/products/PlayVue-giveaway-prizes-1X.jpg?v=1553700635"
                          }
                      }
                  }
              ]
          }
      }
  }
}

Create your custom merchandise representation in game

Using data returned from product request, you are free to create your own representation of product

merch_vertical merch_horizontal


Vertical and horizontal

The merch store view can be created in both vertical and horizontal arrangements. See examples:

vert1 vert2 vert3


hor1 hor2

Make a request to buy merchandise from in-game

To make a purchase event through API you should implement a request for

POST request to https://api3.themonetizr.com/api/products/checkout

The request does need Authorization header and 3 required parameters - product_handle (product id or tag), variantId, quantity (see https://api3.themonetizr.com/docs/#products-checkout)

curl -H "Authorization: Bearer 4D2E54389EB489966658DDD83E2D1" -H "Content-type: application/json" -d '{"variantId":"Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8xNDk3MjcyNzg4NTg5MA==","product_handle":"30-credits", "quantity": "1"}' https://api3.themonetizr.com/api/products/checkout

The response will be json content holding parameters:

  • checkoutUserErrors: array with errors, if they are present, then show feedback to user
  • id: unique id for created shops cart
  • webUrl: Url for completing purchase process, as of now, Monetizr provides url to complete merchandise buying action, this url you should then render in your own game to complete buying. We are working to implement full paymetns functionality through API in near future
{
  "data": {
      "checkoutCreate": {
          "checkoutUserErrors": [],
          "checkout": {
              "id": "Z2lkOi8vc2hvcGlmeS9DaGVja291dC8xMzE0ZDQxMjY4YmMyNWNlNmYxNzZkZWQyZWI1OGZmOD9rZXk9Zjc4YWJjMDU2MDJkMWExZjY0YjA3OWIyNDYzMTkyNTA=",
              "webUrl": "https://shop.themonetizr.com/11335330/checkouts/1314d41268bc25ce6f176ded2eb58ff8?key=f78abc05602d1a1f64b079b246319250",
              "lineItems": {
                  "edges": [
                      {
                          "node": {
                              "title": "1 ticket unlocked. Redeem now!",
                              "quantity": 1
                          }
                      }
                  ]
              }
          }
      }
  }
}

The next steps would be to implement data gathering, Monetizr are considering and weighing on options to understand if we would be willing to open data gathering over access token or allow it only through proper authorization process.


Contact Information

If you have other questions, book a meeting.

I’m also available at 📧 martins@themonetizr.com 📱🇺🇸: +1 917-943-8791

martins

Got questions? Contact me!

Martins