How to set up Pay Station analytics in GTM

How it works

This instruction covers the basic integration of third-party web analytics into the Xsolla Pay Station payment flow and explains how to get valuable data from events and parameters.

Note
Keep in mind that various external factors (script-blockers, disconnects, flow drop, or session expiration) affect the accuracy of any web analytics.

How to get it

To integrate web analytics, perform the following Google Tag Manager (GTM) settings:

  1. Add script to the custom HTML tag.
  2. Define variables.
  3. Add triggers.
  4. Add tags.
  5. Publish changes.

Note

If you change a component of the already integrated web analytics for the payment UI, you only need to publish changes to apply them. You don’t have to adjust the settings of the other components.

Example: If you add the custom HTML tag and the variables have been already defined, publish only the changes related to the tag. You don’t need to repeatedly set up other web analytics components.

Add script to the custom HTML tag

  1. Open your account in GTM and go to Tags.
  2. Click New.

  1. Click the Tag Configuration area.
  2. Choose the Custom HTML tag type from the list.

  1. In the HTML field, paste the following code.

Note
To test the script in the sandbox mode, set the event.origin parameter to https://sandbox-secure.xsolla.com.
Copy
Full screen
Small screen
<script>
window.onmessage = function payStationStatus(event) {
  if (event.origin === "https://secure.xsolla.com") {
    try {
      var data = JSON.parse(event.data).data;           

      if (data.action === 'change-status') {
          dataLayer.push({'event': 'status', 'changeStatus': true, 'status': data.value})
      }

      if (data.action === 'choose-method' && data.value) {
        dataLayer.push({'event': 'choosePaymentMethod', 'choosePaymentMethod': true, 'paymentMethod': data.value})       
      }

      if (data.action === 'click-btn-pay') {
          dataLayer.push({'event': 'clickPayButton', 'clickPayButton': true})
      }

      if (data.action === 'close-widget') {       
          dataLayer.push({'event': 'closeWidget', 'closeWidget': true})
      }

      if (data.action === 'create-invoice') {
          dataLayer.push({
    'event': 'invoiceCreated',
            'invoiceCreated': true,
            'action': data.action,
    'coupon_code': data.coupon_code,
    'date': data.date,
    'milliseconds': data.milliseconds,
    'payment_country': data.payment_country,
    'purchase_currency': data.purchase_currency,
    'purchase_description': data.purchase_description,
    'purchase_external_id': data.purchase_external_id,
    'purchase_invoice_id': data.purchase_invoice_id,
    'purchase_sku': data.purchase_sku,
    'purchase_digital_content_sku': data.purchase_digital_content_sku,
    'purchase_sum': data.purchase_sum,
    'purchase_type': data.purchase_type,
    'session_id': data.session_id,
    'state': data.state,
    'timezone': data.timezone,
    'user_country': data.user_country,
    'user_id': data.user_id,
    'value': data.value,
    'virtual_currency_amount': data.virtual_currency_amount
          });
      }

      if (data.state) {
          dataLayer.push({'event': 'changeState', 'changeState': true, 'state': data.state});
      }
    } catch (e) {
      return;
    }
  }
};
</script>

  1. Click the Triggering area.
  2. Select a trigger with the Page View type firing on all pages.
  3. Click Save.

The saved HTML tag will be displayed in the Tags section. The script execution will be triggered by the payment UI opening.

Define variables

There are two sets of Data Layer variables you need to define, including:

  • Events — used to create triggers and have predefined values.
  • Parameters — used to feed information to an analytics system and can return any values.

How to add a variable:

Events

EventDescription
show-error-pageDisplaying an error. The error text is passed in value.
open-{state_name}Opening a page in the payment UI.
create-invoiceCreating an invoice on Xsolla’s side.
close-widgetClosing the payment UI.
click-email-submitSending an email from the status page.
click-custom-package-continueClicking the Continue button when buying an arbitrary amount of virtual currency.
click-commentClicking the button to post a comment.
click-buy-packageClicking the Buy Package button when buying a package of virtual currency.
click-buy-gift-packageClicking the button when buying a package of virtual currency as a gift.
click-buy-gift-custom-packageClicking the button when buying an arbitrary amount of virtual currency as a gift.
click-btn-shareClicking the button to share via a social network. The social network name is passed in value.
click-btn-payClicking the Pay Now button on the billing data entry form.
click-btn-continueClicking the button to buy the subscription.
click-btn-applyClicking the Apply button when redeeming a coupon.
click-btn-activateClicking the Activate button when activating a game key.
click-btn-acceptClicking the button to buy digital content.
choose-payment-widgetClicking on the payment method widget. The widget name is passed in value.
choose-methodSelecting the payment method. The payment method name is passed in value.
change-statusChanging the payment status. If the user closes the payment UI or leaves the page, and then the status changes, the event message is not sent.
external-link-openRedirection to an external resource. The address to which the redirection occurred is passed in the url parameter.
dimensionsWhen Pay Station opens in the iframe, the width and height of the iframe are passed in the width and height parameters.
status-redeemThe coupon redemption in a payment form.
focus-changeChanging the focus on elements of the Pay Station widget. The focus state is passed in the hasFocus parameter and can be true or false.
statusGoing to the payment status page. The following parameters can be passed:
  • status — payment status
  • email — user’s email
  • invoice — transaction ID
  • virtualCurrencyAmount — the amount of purchased virtual currency
  • userId — user ID
  • discount — the discount applied to the payment
external-payment-openedRedirection from the payment UI to an external payment system or 3-D Secure verification.
returnGoing to the next step after making a payment on the payment system page. If the user is returned to Pay Station, the name of the step is passed in the nextState parameter. If the user is redirected to an external resource, the page address is passed in the redirectUrl parameter.
add_saved_account_errorError occuring while saving a payment account.
cancel_save_accountCancellation of the saving of a payment account by a user.
add_saved_accountSuccessful saving of a payment account.

Parameters

ParameterTypeDescription
actionstringEvent name.
valuestringAdditional parameter. Contains specific event parameters that vary depending on the user’s choice.
statestringThe payment UI page, on which the action was performed.
datestringDate and time in the GMT format.
millisecondsnumberDate and time in the Unix time format.
timezonestringUser time zone.
session_idstringSession ID. The session includes all user actions performed within 30 minutes or until the payment UI is closed. The session starts from the moment when the payment UI is opened and is saved after the page with the payment UI is refreshed.
payment_countrystringPayment country.
purchase_invoice_idnumberPayment invoice ID in the Xsolla system.
purchase_external_idstringPayment invoice ID in the partner’s system.
purchase_typestringPurchase type. Can be: virtual item, virtual currency, pay2play, subscription.
purchase_sumnumberNominal purchase amount.
purchase_currencystringPurchase currency.
purchase_skustringSKU of the purchased item.
purchase_digital_content_skustringSKU of the purchased game keys package.
purchase_descriptionstringPurchase description.
virtual_currency_amountnumberVirtual currency amount.
coupon_codestringCoupon code.
subscription_package_external_idnumberSubscription ID.
subscription_package_namestringSubscription name.
subscription_package_descriptionstringSubscription description.
total_sumnumberTotal purchase amount. All fees are included.
total_sum_currencystringTotal purchase amount currency.
user_idstringUser ID (v1).
user_countrystringUser country.
payment_instance_namestringPayment method name.

Add triggers

To add a trigger, you need one or more Data Layer variables listed under events.

EXAMPLE: We want to send information to Facebook after a user visited the payment status page.

Add tags

This step depends on the web analytics system you use. As an example, we’ll review Google Analytics.

EXAMPLE: A user goes to the status page. We want to transfer this event information, as well as the payment amount and currency, to Google Analytics (currency is a custom metric in our Google Analytics).

Note
For purchase events, we strongly recommend user payment confirmation — clickPayButton — as any further event requires a user to keep the browser window open; it’s not always the case that transaction confirmation gets postMessage initiation before a user closes the tab.

Publish changes

  1. Go to Overview and click Submit.

  1. In the Publish and Create Version tab, indicate a version name, its description, and a publication environment.
  2. Click Publish.
  3. Was this article helpful?
    Thank you!
    Is there anything we can improve? Message
    We’re sorry to hear that
    Please explain why this article wasn’t helpful to you. Message
    Thank you for your feedback!
    We’ll review your message and use it to help us improve your experience.
    Rate this page
    Rate this page
    Is there anything we can improve?

    Don’t want to answer

    Thank you for your feedback!
    Last updated: May 16, 2022

    Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!