# Gamepix Integration Documentation

This documentation provides detailed steps on how to integrate Gamepix games into your website or web application using iframes or webviews. The integration can be achieved by utilizing the Gamepix RSS feed to fetch game data and embedding the game URLs directly into your site.

# Fetching Game Data
You can fetch all available games from Gamepix using the provided RSS feed. The feed is available in both JSON and XML formats:

JSON: https://feeds.gamepix.com/v2/json?sid=1
XML: https://feeds.gamepix.com/v2/xml?sid=1

# Query Parameters
The following query parameters can be used to customize the feed:

* category: Filters games by category. The available categories can be found at https://public.gamepix.com/json/feeds/v2/games/category/list.json
* order: Sorts games by `quality` or `pubdate`.
* page: Specifies the page number for pagination.
* pagination: Sets the number of items per page. Acceptable values are 12, 24, 48, and 96.
* sid: Your partner site ID provided by Gamepix.

# Example Request
To fetch games sorted by quality, displaying 24 games per page, from the first page for a specific partner site ID (sid=1):  https://feeds.gamepix.com/v2/json?order=quality&page=1&pagination=24&sid=1

# Response Format
The response is a JSON object with the following structure:

json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "My GamePix Games",
  "home_page_url": "https://www.gamepix.com/",
  "feed_url": "https://feeds.gamepix.com/v2/json/?order=quality&page=1&pagination=24&sid=1",
  "next_url": "https://feeds.gamepix.com/v2/json/?order=quality&page=2&pagination=24&sid=1",
  "first_page_url": "https://feeds.gamepix.com/v2/json/?order=quality&page=1&pagination=24&sid=1",
  "last_page_url": "https://feeds.gamepix.com/v2/json/?order=quality&page=271&pagination=24&sid=1",
  "modified": "Thu, 23 May 2024 00:05:31 GMT",
  "items": [
     {
      "id": "O6650",
      "title": "My First 100 Words",
      "namespace": "my-100-first-words",
      "description": "Small children can learn their first +100 words in several languages by playing this fun game. It starts displaying different emojis and plays an audio with the pronunciation in the selected language. Then they are verbally asked to find some emojis. It gets more challenging over time!",
      "category": "kids",
      "orientation": "portrait",
      "quality_score": 0.915487414720237,
      "width": 600,
      "height": 800,
      "date_modified": "Mon, 24 Apr 2023 09:11:34 GMT",
      "date_published": "Wed, 26 Oct 2022 16:24:37 GMT",
      "banner_image": "https://img.gamepix.com/games/my-100-first-words/cover/small.png?w=320",
      "image": "https://img.gamepix.com/games/my-100-first-words/icon/small.png?w=105",
      "url": "https://play.gamepix.com/my-100-first-words/embed?sid=1"
    },
    {
      "id": "E6O54",
      "title": "Cerkio",
      "namespace": "cerkio",
      "description": "Touch the screen at the right time to throw the ball in the white circle.\nRepeat it for more than 30 levels and prove yourself you are skilled enough to complete the game!\n\n34 levels\nNice music\nRelaxing game\none hand game",
      "category": "ball",
      "orientation": "portrait",
      "quality_score": 0.915410986901778,
      "width": 600,
      "height": 800,
      "date_modified": "Wed, 15 Sep 2021 14:04:18 GMT",
      "date_published": "Tue, 07 Sep 2021 10:43:06 GMT",
      "banner_image": "https://img.gamepix.com/games/cerkio/cover/small.png?w=320",
      "image": "https://img.gamepix.com/games/cerkio/icon/small.png?w=105",
      "url": "https://play.gamepix.com/cerkio/embed?sid=1"
    },
    { ... },
    { ... }
  ]
}

# Embedding Games via Iframe

To embed a Gamepix game on your website using an iframe, follow these steps:
* Create the iframe Element: Dynamically create an iframe element in your HTML.
* Set the Iframe Attributes: Configure the iframe with the game URL and appropriate attributes.
* Append the Iframe to Your Webpage: Insert the iframe into your webpage's DOM.

# Example Code

javascript
/**
   * GLOBAL VARS
   */
  let sid = "1"; // Put here your Gamepix ID
  let gameNamespace = "flamit"; // The namespace of the game you want to embed

  /**
   * Function to handle the score and level updates from the game
   */
  function handleGameEvent({ type, level, score }) {
    if (type) console.log(type);
    if (level) console.log('level', level);
    if (score) console.log('score', score);
  }

  /**
   * Initialize and embed the game iframe
   */
  function init() {
    // 1. Create the iframe
    var iframe = document.createElement('iframe');
    iframe.id = 'game-frame';
    iframe.src = `https://play.gamepix.com/${gameNamespace}/embed?sid=${sid}`;
    iframe.setAttribute('frameborder', '0');
    iframe.setAttribute('name', window.location.href);
    iframe.setAttribute('width', '100%');
    iframe.setAttribute('height', '100%');
    iframe.setAttribute('scrolling', 'no');
    iframe.style.top = '0';
    iframe.style.left = '0';

    // 2. Set up parent-child communication
    var eventMethod = window.addEventListener ? 'addEventListener' : 'attachEvent';
    var eventer = window[eventMethod];
    var messageEvent = eventMethod == 'attachEvent' ? 'onmessage' : 'message';

    // Listen to messages from the child window
    eventer(messageEvent, function (e) {
      switch (e.data.type) {
        case 'update_score':
          handleGameEvent({ type: 'score', score: e.data.score });
          break;
        case 'update_level':
          handleGameEvent({ type: 'level', level: e.data.level });
          break;
      }
    }, false);

    // Append the iframe to the body
    document.body.appendChild(iframe);
  }

  // Initialize the game embedding
  init();

# Embedding Games via Webview
To embed a Gamepix game in a webview (for mobile apps or other environments), follow these steps:
* Load the Game URL in the Webview: Use the provided game URL directly in your webview.
* Listen for Game Events: Use the window.$GPX event listener to capture game events such as score and level updates. 

# Example Code for Webview
Ensure your webview component is properly configured to allow JavaScript execution and event listening. Here's a basic example for integrating with a webview in a JavaScript environment:

javascript
// Example code for embedding Gamepix games in a webview

// Load the game URL in the webview
const gameNamespace = "flamit";
const sid = "YOUR_GPXID"; // Your Gamepix ID
const gameUrl = `https://play.gamepix.com/${gameNamespace}/embed?sid=${sid}`;

// Assuming you have a webview element with id "game-webview"
const webview = document.getElementById('game-webview');
webview.src = gameUrl;

// Set up event listeners for game events once the webview is ready
webview.onload = () => {
  // Assuming you have a way to execute JavaScript inside the webview context
  webview.contentWindow.eval(`
    window.$GPX.addEventListener('update_score', ({score}) => {
      console.log('The new score is:', score);
    });
    window.$GPX.addEventListener('update_level', ({level}) => {
      console.log('The new level is:', level);
    });
  `);
};

# Handling Events
When using the iframe or webview, you need to handle the events sent by the Gamepix games. These events are `update_score` and `update_level`, and they provide details such as the score or the current level of the game.

# Conclusion
Integrating Gamepix games into your website or web application is straightforward using iframes or webviews. By following the steps outlined in this documentation, you can embed games and handle game events efficiently. Make sure to customize the provided code examples with your specific Gamepix ID (sid) and game namespace to ensure proper functionality. For any further customization or advanced integrations, refer to the Gamepix API documentation and resources.