.. _hands-history-label:

Hands History
*************

**Hands History** is an online tool, which is used for game rounds visualizing. This tool is mainly (and should be) used by support team.
After access URL is generated, it can be pasted into ``iframe`` tag or opened in a new tab.


Access to Hands History interface
#################################

**Common view of Hands History URL:**

 ``{PLATFORM_SERVER_URL}/{PROJECT_NAME}/history.html#{PARAMS}``

 ``{PLATFORM_SERVER_URL}`` is game server URL (it will be provided by integration manager). In our examples we use "https://gaterc.example.com/op", but in your case URL may be different.

 ``{PROJECT_NAME}`` is a name of the project (it will be provided by integration manager). In our examples we use "arena-rc", but in your case it may be different.

 ``{PARAMS}`` is described in the consequent parts below.

.. attention::

     All parameters are passed as URL hash fragments.


Player's games interface
########################

.. figure:: images/handshistory/playergames.png
    :align: center

    Figure 1 - Player's games interface


``{PARAMS}`` can contain the following parameters:

   ==========  =============  ==============================  ========
   Parameter   Value                                          Description
   ==========  =============  ==============================  ========
   player_id   string         mandatory                       Unique player identifier.
   brand       string         mandatory/optional              Player's brand. Mandatory if the same ``player_id`` is present on different ``brand``.
   game_id     integer        optional                        Unique game ID. Can be empty to display all games.
   start_date  YYYYMMDDTHHmm  optional                        Starting date, ISO-8601.
   end_date    YYYYMMDDTHHmm  optional                        Ending date, ISO-8601.
   mode        string         optional, *REAL* by default     Game mode. One of "REAL" or "FUN".
   tz          integer        optional                        Timezone offset in minutes (tz=120 - +2 hours).
   header      integer        optional, *1* by default        Show/hide interface header with search forms. 1 - show header, 0 - hide it.
   totals      integer        optional, *1* by default        Show/hide **Totals** widget. 1 - show widget, 0 - hide it.
   lang        string         optional, *en* by default       Language setting. Currently ``en``, ``zh`` and ``zh-hant`` localizations are available.
   realtime    integer        optional, *1* by default        1 - show the most recent data, but with 0 round games can be present within the selected time period. 0 - show data with 5-10 minutes delay from now, but 0 round games will be filtered out of the search result.
   ==========  =============  ==============================  ========


**Example of a URL for getting an information about all games:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#player_id=1

**Example of a URL for getting an information about a specific game:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#player_id=1&game_id=1

**Example of a URL for getting an information about all games in a certain period of time (e.g., for September, +3 TimeZone):**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#player_id=1&start_date=20180901T0000&end_date=20180930T2359&tz=180

**Example of a URL of a fully customized Player Games interface:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#player_id=1&start_date=20180901T0000&end_date=20180930T2359&tz=480&header=0&totals=0&realtime=0&mode=REAL&lang=en


**Search form:**

================  ========
Parameter         Description
================  ========
Game              Game selection from available games list.
Game Mode         Game mode selection. One of "FUN" or "REAL".
Round             Round ID.
Date Range        Date period. It is used for fetch limiting. You can set timezone in date picker.
================  ========

.. note::
  If **Round** is specified in search form then all other search parameters are ignored.

**Search result:**

================  ========
Parameter         Description
================  ========
Game              Game code and localized game title (including a link to the Transactions view).
Currency          Player's currency.
Rounds            Amount of rounds played by a player.
Bets              Bets total.
Wins              Wins total.
Outcome           Difference between player's win and bet.
Payout            Player's payout rate.
================  ========



Player's transactions interface
################################

.. figure:: images/handshistory/transactions.png
 :align: center

 Figure 2 - Player's transactions interface


``{PARAMS}`` can contain the following parameters:

   ==========  =============  ==============================  ========
   Parameter   Value                                          Description
   ==========  =============  ==============================  ========
   show        transactions   mandatory                       Static value.
   player_id   string         mandatory                       Unique player identifier.
   brand       string         mandatory/optional              Player's brand. Mandatory if the same ``player_id`` is present on different ``brand``.
   game_id     integer        mandatory                       Unique game ID.
   currency    string         mandatory                       Currency name.
   start_date  YYYYMMDDTHHmm  optional                        Starting date, ISO-8601.
   end_date    YYYYMMDDTHHmm  optional                        Ending date, ISO-8601.
   round_id    string         optional                        Round ID.
   mode        string         optional, *REAL* by default     Game mode. One of "REAL" or "FUN".
   tz          integer        optional                        Timezone offset in minutes (tz=120 - +2 hours).
   header      integer        optional, *1* by default        Show/hide interface header with search forms. 1 - show header, 0 - hide it.
   totals      integer        optional, *1* by default        Show/hide **Totals** widget. 1 - show widget, 0 - hide it.
   lang        string         optional, *en* by default       Language setting. Currently ``en``, ``zh`` and ``zh-hant`` localizations are available.
   per_page    integer        optional, *100* by default      An amount of transactions shown per page.
   ==========  =============  ==============================  ========

.. note::

  All data at Transactions interface are shown in real time without delays.

**Example of a URL for getting transactions information about a specific game for the whole period of time:**

.. code-block:: none

 https://gaterc.example.com/op/arena-rc/history.html#player_id=1&show=transactions&game_id=1&mode=REAL&currency=USD

**Example of a URL for getting transactions information about a specific game for September:**

.. code-block:: none

 https://gaterc.example.com/op/arena-rc/history.html#player_id=1&show=transactions&game_id=1&start_date=20160901T0000&end_date=20160930T2359&mode=REAL&currency=USD

**Example of a URL of a fully customized Transactions interface:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#player_id=1&show=transactions&game_id=1&tz=120&start_date=20180901T0000&end_date=20180930T2359&per_page=10&round_id=717015000001&currency=USD&mode=REAL&header=0&totals=0&lang=en

.. tip::
  If you require a URL pointing to the exact transaction ``uid`` result, you can do that using the following format of the URL:

  ``{PLATFORM_SERVER_URL}/{PROJECT_NAME}/history/draw/{TRANSACTION_UID}``

**Example of a URL pointing to the exact transaction uid:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc1/history/draw/c40c0c9475074f6d9fedc70809f94341/


**Search form:**

================  ========
Parameter         Description
================  ========
Game              Game selection from available games list.
Game Mode         Game mode selection. One of "FUN" or "REAL".
Round             If you want to view an information on specific round, enter round ID in the text form.
Date Range        Date period. It is used for fetch limiting. You can set timezone in date picker.
================  ========

.. note::

    Sorting is performed by date by default. It is impossible to change that.

**Search result:**

==============  ========
Parameter       Description
==============  ========
ID              Click on info label will show transaction ID.
Date            Transaction confirmation date (according to selected timezone).
Currency        Player's currency.
Balance Before  Player's balance before a round.
Bet             Player's bet.
Win             Player's win.
Outcome         Difference between player's win and bet.
Balance After   Player's balance after a round.
Round           Round ID including URL to a round visualization.
==============  ========

.. attention::

    When the player selects an object in bonus game the bet is absent, but there is a win. Also  **bet** can be negative in case of ROLLBACK transaction.


Player's round interface
################################

.. figure:: images/handshistory/round.png
 :align: center

 Figure 3 - Player's round interface


``{PARAMS}`` can contain the following parameters:

   ==========  =============  ==============================  ========
   Parameter   Value                                          Description
   ==========  =============  ==============================  ========
   show        round          mandatory                       Static value.
   round_id    string         mandatory                       Round ID.
   player_id   string         optional                        Unique player identifier.
   brand       string         mandatory/optional              Player's brand. Mandatory if the same ``player_id`` is present on different ``brand``.
   tz          integer        optional                        Timezone offset in minutes (tz=120 - +2 hours).
   header      integer        optional, *1* by default        Show/hide interface header with search forms. 1 - show header, 0 - hide it.
   totals      integer        optional, *1* by default        Show/hide **Totals** widget. 1 - show widget, 0 - hide it.
   balance     integer        optional, *0* by default        Show/hide **Balance Before** and **Balance After** columns.
   lang        string         optional, *en* by default       Language setting. Currently ``en``, ``zh`` and ``zh-hant`` localizations are available.
   ==========  =============  ==============================  ========

.. note::

  All data at Round interface are shown in real time without delays.

**Example of a URL for getting a round information:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#round_id=1&show=round

**Example of a URL for getting a round information including Balance Before/Balance After columns:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#round_id=1&show=round&balance=1

**Example of a URL of a fully customized Round interface:**

.. code-block:: none

  https://gaterc.example.com/op/arena-rc/history.html#player_id=400&show=round&tz=480&round_id=717048800001&header=0&totals=0&balance=1&lang=en


**Search form:**

================  ========
Parameter         Description
================  ========
Round             If you want to view an information on specific round, enter round ID in the text form.
================  ========

.. note::

    Sorting is performed by date by default. It is impossible to change that.

**Search result:**

==============  ========
Parameter       Description
==============  ========
ID              Click on an info label will show the transaction ID.
Game            Game code and localized game title.
Date            Transaction confirmation date (according to selected timezone).
Currency        Player's currency.
Balance Before  Player's balance before a round. Visible only when ``balance=1`` parameter is passed.
Bet             Player's bet.
Win             Player's win.
Outcome         Difference between player's win and bet.
Balance After   Player's balance after a round. Visible only when ``balance=1`` parameter is passed.
Round           Round ID including URL to a round visualization.
==============  ========


Basic integration using jQuery
##############################

.. code-block:: html

 <html>
 <body>
 ...
     <div id="handshistory-container"></div>
     <script>
         (function($, options) {

             // Generating iframe's HTML code:

             var src = '{PLATFORM_SERVER_URL}/{PROJECT_NAME}/history.html#player_id={PLAYER_ID}'
                 .replace('{PLATFORM_SERVER_URL}', options.gameServerURL)
                 .replace('{PROJECT_NAME}', options.projectName)
                 .replace('{PLAYER_ID}', options.playerID);

             var $iframe = $('<iframe>', {
                 allowtransparency: 'true',
                 width: '100%',
                 height: '100%',
                 frameborder: '0',
                 src: src
             });

             // iframe rendering:

             options.$container.html($iframe);

         })(jQuery,  {
             $container:  $("#handshistory-container"),              // parent container
             gameServerURL: "https://gaterc.example.com/op",         // this value is provided by integration manager
             projectName: "arena-rc",                                // this value is provided by integration manager
             playerID: "1"
         });
     </script>
 ...
 </body>
 </html>


Automatic iframe resizing integration
#####################################

If parent container size is not enough for proper displaying, iframe may contain scrollers in the example above.

Hands History's iframe passes its size (width and height in pixels) via window.postMessage method. This feature allows to change a size of parent container and to avoid appearance of unnecessary scrollers.

.. code-block:: html

    <html>
    <body>
    ...
        <div id="handshistory-container"></div>
        <script>
            (function($, options) {

                // Container resizing:

                $(window).on('message', function(event) {
                    var data = JSON.parse(event.originalEvent.data);
                    if (data.event == 'handshistory:resize') {
                        options.$container.css({
                            height: data.dimensions.height + 'px'
                        });
                    }
                });

                // Generating iframe's HTML code:

                var src = '{PLATFORM_SERVER_URL}/{PROJECT_NAME}/history.html#player_id={PLAYER_ID}'
                    .replace('{PLATFORM_SERVER_URL}', options.gameServerURL)
                    .replace('{PROJECT_NAME}', options.projectName)
                    .replace('{PLAYER_ID}', options.playerID);

                var $iframe = $('<iframe>', {
                    allowtransparency: 'true',
                    width: '100%',
                    height: '100%',
                    frameborder: '0',
                    src: src
                });

                // iframe rendering:

                options.$container.html($iframe);

            })(jQuery, {
                $container:  $("#handshistory-container"),              // parent container
                gameServerURL: "https://gaterc.example.com/op",         // this value is provided by integration manager
                projectName: "arena-rc",                                // this value is provided by integration manager
                playerID: "1"
            });
        </script>
    ...
    </body>
    </html>