mirror of
https://github.com/pretix/pretix.git
synced 2025-12-15 14:02:27 +00:00
348 lines
16 KiB
ReStructuredText
348 lines
16 KiB
ReStructuredText
.. _widget:
|
|
|
|
Embeddable Widget
|
|
=================
|
|
|
|
If you want to show your ticket shop on your event website or blog, you can use our JavaScript widget. This way,
|
|
users will not need to leave your site to buy their ticket in most cases. The widget will still open a new tab
|
|
for the checkout if the user is on a mobile device.
|
|
|
|
To obtain the correct HTML code for embedding your event into your website, we recommend that you go to the "Widget"
|
|
tab of your event's settings. You can specify some optional settings there (for example the language of the widget)
|
|
and then click "Generate widget code".
|
|
|
|
.. thumbnail:: ../../screens/event/widget_form.png
|
|
:align: center
|
|
:class: screenshot
|
|
|
|
You will obtain two code snippets that look *roughly* like the following. The first should be embedded into the
|
|
``<head>`` part of your website, if possible. If this inconvenient, you can put it in the ``<body>`` part as well::
|
|
|
|
<link rel="stylesheet" type="text/css" href="https://pretix.eu/demo/democon/widget/v1.css">
|
|
<script type="text/javascript" src="https://pretix.eu/widget/v1.en.js" async></script>
|
|
|
|
The second snippet should be embedded at the position where the widget should show up::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/"></pretix-widget>
|
|
<noscript>
|
|
<div class="pretix-widget">
|
|
<div class="pretix-widget-info-message">
|
|
JavaScript is disabled in your browser. To access our ticket shop without JavaScript,
|
|
please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
|
|
</div>
|
|
</div>
|
|
</noscript>
|
|
|
|
.. note::
|
|
|
|
You can of course embed multiple widgets of multiple events on your page. In this case, please add the first
|
|
snippet only *once* and the second snippets once *for each event*.
|
|
|
|
.. note::
|
|
|
|
Some website builders like Jimdo have trouble with our custom HTML tag. In that case, you can use
|
|
``<div class="pretix-widget-compat" …></div>`` instead of ``<pretix-widget …></pretix-widget>`` starting with
|
|
pretix 1.14.
|
|
|
|
Example
|
|
-------
|
|
|
|
Your embedded widget could look like the following:
|
|
|
|
.. raw:: html
|
|
|
|
<link rel="stylesheet" type="text/css" href="https://pretix.eu/demo/democon/widget/v1.css">
|
|
<script type="text/javascript" src="https://pretix.eu/widget/v1.en.js" async></script>
|
|
<pretix-widget event="https://pretix.eu/demo/democon/"></pretix-widget>
|
|
<noscript>
|
|
<div class="pretix-widget">
|
|
<div class="pretix-widget-info-message">
|
|
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
|
|
</div>
|
|
</div>
|
|
</noscript>
|
|
|
|
|
|
Styling
|
|
-------
|
|
|
|
If you want, you can customize the appearance of the widget to fit your website with CSS. If you inspect the rendered
|
|
HTML of the widget with your browser's developer tools, you will see that nearly every element has a custom class
|
|
and all classes are prefixed with ``pretix-widget``. You can override the styles as much as you want to and if
|
|
you want to go all custom, you don't even need to use the stylesheet provided by us at all.
|
|
|
|
SSL
|
|
---
|
|
|
|
Since buying a ticket normally involves entering sensitive data, we strongly suggest that you use SSL/HTTPS for the page
|
|
that includes the widget. Initiatives like `Let's Encrypt`_ allow you to obtain a SSL certificate free of charge.
|
|
|
|
All data transferred to pretix will be made over SSL, even if using the widget on a non-SSL site. However, without
|
|
using SSL for your site, a man-in-the-middle attacker could potentially alter the widget in dangerous ways. Moreover,
|
|
using SSL is becoming standard practice and your customers might want expect see the secure lock icon in their browser
|
|
granted to SSL-enabled web pages.
|
|
|
|
By default, the checkout process will open in a new tab in your customer's browsers if you don't use SSL for your
|
|
website. If you confident to have a good reason for not using SSL, you can override this behavior with the
|
|
``skip-ssl-check`` attribute::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/" skip-ssl-check></pretix-widget>
|
|
|
|
Pre-selecting a voucher
|
|
-----------------------
|
|
|
|
You can pre-select a voucher for the widget with the ``voucher`` attribute::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/" voucher="ABCDE123456"></pretix-widget>
|
|
|
|
This way, the widget will only show products that can be bought with the voucher and prices according to the
|
|
voucher's settings.
|
|
|
|
.. raw:: html
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/" voucher="ABCDE123456"></pretix-widget>
|
|
<noscript>
|
|
<div class="pretix-widget">
|
|
<div class="pretix-widget-info-message">
|
|
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
|
|
</div>
|
|
</div>
|
|
</noscript>
|
|
|
|
Disabling the voucher input
|
|
---------------------------
|
|
|
|
If you want to disable voucher input in the widget, you can pass the ``disable-vouchers`` attribute::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/" disable-vouchers></pretix-widget>
|
|
|
|
Filtering products
|
|
------------------
|
|
|
|
You can filter the products shown in the widget by passing in a list of product IDs::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/" items="23,42"></pretix-widget>
|
|
|
|
Alternatively, you can select one or more categories to be shown::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/" categories="12,25"></pretix-widget>
|
|
|
|
Multi-event selection
|
|
---------------------
|
|
|
|
If you want to embed multiple events in a single widget, you can do so. If it's multiple dates of an event series, just leave off the ``series`` attribute::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/series/"></pretix-widget>
|
|
|
|
If you want to include all your public events, you can just reference your organizer::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/"></pretix-widget>
|
|
|
|
There is an optional ``style`` parameter that let's you choose between a monthly calendar view, a week view and a list
|
|
view. If you do not set it, the choice will be taken from your organizer settings::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/series/" style="list"></pretix-widget>
|
|
<pretix-widget event="https://pretix.eu/demo/series/" style="calendar"></pretix-widget>
|
|
<pretix-widget event="https://pretix.eu/demo/series/" style="week"></pretix-widget>
|
|
|
|
If you have more than 100 events, the system might refuse to show a list view and always show a calendar for performance
|
|
reasons instead.
|
|
|
|
You can see an example here:
|
|
|
|
.. raw:: html
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/series/" style="calendar"></pretix-widget>
|
|
<noscript>
|
|
<div class="pretix-widget">
|
|
<div class="pretix-widget-info-message">
|
|
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/series/">click here</a>.
|
|
</div>
|
|
</div>
|
|
</noscript>
|
|
|
|
You can filter events by meta data attributes. You can create those attributes in your order profile and set their values in both event and series date
|
|
settings. For example, if you set up a meta data property called "Promoted" that you set to "Yes" on some events, you can pass a filter like this::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/series/" style="list" filter="attr[Promoted]=Yes"></pretix-widget>
|
|
|
|
pretix Button
|
|
-------------
|
|
|
|
Instead of a product list, you can also display just a single button. When pressed, the button will add a number of
|
|
products associated with the button to the cart and will immediately proceed to checkout if the operation succeeded.
|
|
You can try out this behavior here:
|
|
|
|
.. raw:: html
|
|
|
|
<pretix-button event="https://pretix.eu/demo/democon/" items="item_6424=1">Buy ticket!</pretix-button>
|
|
<noscript>
|
|
<div class="pretix-widget">
|
|
<div class="pretix-widget-info-message">
|
|
JavaScript is disabled in your browser. To access our ticket shop without javascript, please <a target="_blank" href="https://pretix.eu/demo/democon/">click here</a>.
|
|
</div>
|
|
</div>
|
|
</noscript>
|
|
<br><br>
|
|
|
|
You can embed the pretix Button just like the pretix Widget. Just like above, first embed the CSS and JavaScript
|
|
resources. Then, instead of the ``pretix-widget`` tag, use the ``pretix-button`` tag::
|
|
|
|
<pretix-button event="https://pretix.eu/demo/democon/" items="item_6424=1">
|
|
Buy ticket!
|
|
</pretix-button>
|
|
|
|
As you can see, the ``pretix-button`` element takes an additional ``items`` attribute that specifies the items that
|
|
should be added to the cart. The syntax of this attribute is ``item_ITEMID=1,item_ITEMID=2,variation_ITEMID_VARID=4``
|
|
where ``ITEMID`` are the internal IDs of items to be added and ``VARID`` are the internal IDs of variations of those
|
|
items, if the items have variations. If you omit the ``items`` attribute, the general start page will be presented.
|
|
|
|
Just as the widget, the button supports the optional attributes ``voucher`` and ``skip-ssl-check``.
|
|
|
|
You can style the button using the ``pretix-button`` CSS class.
|
|
|
|
Dynamically opening the widget
|
|
------------------------------
|
|
|
|
You can get the behavior of the pretix Button without a button at all, so you can trigger it from your own code in
|
|
response to a user action. Usually, this will open an overlay with your ticket shop, however in some cases, such as
|
|
missing HTTPS encryption on your case or a really small screen (mobile), it will open a new tab instead of an overlay.
|
|
Therefore, make sure you call this *in direct response to a user action*, otherwise most browser will block it as an
|
|
unwanted pop-up.
|
|
|
|
.. js:function:: window.PretixWidget.open(target_url [, voucher [, subevent [, items, [, widget_data [, skip_ssl_check ]]]]])
|
|
|
|
:param string target_url: The URL of the ticket shop.
|
|
:param string voucher: A voucher code to be pre-selected, or ``null``.
|
|
:param string subevent: A subevent to be pre-selected, or ``null``.
|
|
:param array items: A collection of items to be put in the cart, of the form ``[{"item": "item_3", "count": 1}, {"item": "variation_5_6", "count": 4}]``
|
|
:param object widget_data: Additional data to be passed to the shop, see below.
|
|
:param boolean skip_ssl_check: Whether to ignore the check for HTTPS. Only to be used during development.
|
|
|
|
Dynamically loading the widget
|
|
------------------------------
|
|
|
|
If you need to control the way or timing the widget loads, for example because you want to modify user data (see
|
|
below) dynamically via JavaScript, you can register a listener that we will call before creating the widget::
|
|
|
|
<script type="text/javascript">
|
|
window.pretixWidgetCallback = function () {
|
|
// Will be run before we create the widget.
|
|
}
|
|
</script>
|
|
|
|
If you want, you can suppress us loading the widget and/or modify the user data passed to the widget::
|
|
|
|
<script type="text/javascript">
|
|
window.pretixWidgetCallback = function () {
|
|
window.PretixWidget.build_widgets = false;
|
|
window.PretixWidget.widget_data["email"] = "test@example.org";
|
|
}
|
|
</script>
|
|
|
|
If you then later want to trigger loading the widgets, just call ``window.PretixWidget.buildWidgets()``.
|
|
|
|
Waiting for the widget to load
|
|
------------------------------
|
|
|
|
If you want to run custom JavaScript once the widget is fully loaded, you can register a callback function. Note that
|
|
this function might be run multiple times, for example if you have multiple widgets on a page or if the user switches
|
|
e.g. from an event list to an event detail view::
|
|
|
|
<script type="text/javascript">
|
|
window.pretixWidgetCallback = function () {
|
|
window.PretixWidget.addLoadListener(function () {
|
|
console.log("Widget has loaded!");
|
|
});
|
|
}
|
|
</script>
|
|
|
|
|
|
Passing user data to the widget
|
|
-------------------------------
|
|
|
|
If you display the widget in a restricted area of your website and you want to pre-fill fields in the checkout process
|
|
with known user data to save your users some typing and increase conversions, you can pass additional data attributes
|
|
with that information::
|
|
|
|
<pretix-widget event="https://pretix.eu/demo/democon/"
|
|
data-attendee-name-given-name="John"
|
|
data-attendee-name-family-name="Doe"
|
|
data-invoice-address-name-given-name="John"
|
|
data-invoice-address-name-family-name="Doe"
|
|
data-email="test@example.org"
|
|
data-question-L9G8NG9M="Foobar">
|
|
</pretix-widget>
|
|
|
|
This works for the pretix Button as well, if you also specify a product.
|
|
Currently, the following attributes are understood by pretix itself:
|
|
|
|
* ``data-email`` will pre-fill the order email field as well as the attendee email field (if enabled).
|
|
|
|
* ``data-question-IDENTIFIER`` will pre-fill the answer for the question with the given identifier. You can view and set
|
|
identifiers in the *Questions* section of the backend.
|
|
|
|
* Depending on the person name scheme configured in your event settings, you can pass one or more of
|
|
``data-attendee-name-full-name``, ``data-attendee-name-given-name``, ``data-attendee-name-family-name``,
|
|
``data-attendee-name-middle-name``, ``data-attendee-name-title``, ``data-attendee-name-calling-name``,
|
|
``data-attendee-name-latin-transcription``. If you don't know or don't care, you can also just pass a string as
|
|
``data-attendee-name``, which will pre-fill the last part of the name, whatever that is.
|
|
|
|
* ``data-invoice-address-FIELD`` will pre-fill the corresponding field of the invoice address. Possible values for
|
|
``FIELD`` are ``company``, ``street``, ``zipcode``, ``city`` and ``country``, as well as fields specified by the
|
|
naming scheme such as ``name-title`` or ``name-given-name`` (see above). ``country`` expects a two-character
|
|
country code.
|
|
|
|
* If ``data-fix="true"`` is given, the user will not be able to change the other given values later. This currently
|
|
only works for the order email address as well as the invoice address. Attendee-level fields and questions can
|
|
always be modified. Note that this is not a security feature and can easily be overridden by users, so do not rely
|
|
on this for authentication.
|
|
|
|
Any configured pretix plugins might understand more data fields. For example, if the appropriate plugins on pretix
|
|
Hosted or pretix Enterprise are active, you can pass the following fields:
|
|
|
|
* If you use the campaigns plugin, you can pass a campaign ID as a value to ``data-campaign``. This way, all orders
|
|
made through this widget will be counted towards this campaign.
|
|
|
|
* If you use the tracking plugin, you can pass a Google Analytics User ID to enable cross-domain tracking. This will
|
|
require you to dynamically load the widget, like this::
|
|
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-XXXXXX-1', 'auto');
|
|
ga('send', 'pageview');
|
|
|
|
window.pretixWidgetCallback = function () {
|
|
window.PretixWidget.build_widgets = false;
|
|
window.addEventListener('load', function() { // Wait for GA to be loaded
|
|
if(window.ga && ga.create) {
|
|
ga(function(tracker) {
|
|
window.PretixWidget.widget_data["tracking-ga-id"] = tracker.get('clientId');
|
|
window.PretixWidget.buildWidgets()
|
|
});
|
|
} else { // Tracking is probably blocked
|
|
window.PretixWidget.buildWidgets()
|
|
}
|
|
});
|
|
};
|
|
</script>
|
|
|
|
In some combinations with Google Tag Manager, the widget does not load this way. In this case, try replacing
|
|
``tracker.get('clientId')`` with ``ga.getAll()[0].get('clientId')``.
|
|
|
|
|
|
.. versionchanged:: 2.3
|
|
|
|
Data passing options have been added in pretix 2.3. If you use a self-hosted version of pretix, they only work
|
|
fully if you configured a redis server.
|
|
|
|
.. versionchanged:: 3.6
|
|
|
|
Dynamically opening the widget has been added in pretix 3.6.
|
|
|
|
.. _Let's Encrypt: https://letsencrypt.org/
|