Widgets

ticketmatic's widgets are being replaced by ticket sales flows docid\ fpj1u4i4rolqyqmbqwo4x that have more functionality and are easier to use you can still use widgets directly, as specified below a widget is a configurable web application that covers a part of the ticket sales process a typical ticket sales process consists of following steps explore events (happens on your website) add tickets to order for an event show basket (optional) checkout widgets allow you to handle each of the steps 2 to 4 individually and allow you to navigate back to your website after each step compared to the plug and play docid\ t2uqek2blpdqf8nbgiq0f which handles steps 2 4 in a single, straightforward wizard, this gives you much more flexibility to setup a ticket sales process that is tailored to your individual need some examples of what you can achieve you can let the user iterate between steps 1 and 2 to allow the user to add tickets for more than 1 event to his order you can provide your own upselling page, right before going to checkout widgets can be used embedded or standalone an embedded widget is displayed inside your website (using an iframe) a standalone widget is displayed in a complete browser window embedded widgets used inside an iframe require the use of a custom domain that is on the same domain as your website (for example tickets mydomain com ) generating a widget url you use a widget by generating a widget url and simply linking to it when generating a widget url, you specify the parameters to configure the widget and then you need to generate a signature (to avoid tampering with the widget url) the easiest way to generate a widget url is by using one of the api libraries https //www ticketmatic com/docs/api/#libraries each library contains a helper class to generate widget urls and generating the signatures is provided by the library php the signing helper is ticketmatic\widgets instantiate it with your account name and widget keys use ticketmatic\widgets; $widgets = new widgets($accountname, $accesskey, $privatekey); pass a widget name and a set of parameters to sign the url $url = $widgets >generateurl("addtickets", array( "event" => 123, "skinid" => 1, "returnurl" => "http //www ticketmatic com", "l" => "en", )); go the signing helper is ticketmatic widgets instantiate it with your account name and widget keys import "github com/ticketmatic/tm go/ticketmatic" widgets = ticketmatic newwidgets(accountname, accesskey, privatekey) pass a widget name and a map\[string]string with parameters to sign the url url = widgets generateurl("addtickets", map\[string]string{ "event" "123", "skinid" "1", "returnurl" "http //www ticketmatic com", "l" "en", }) if you don't find a suitable library or if you prefer to generate the widget urls yourself you can widgets docid\ xy bxjznntsula bjnc v configuring widgets you configure widgets by providing the parameters you want most parameters are optional, when omitting them ticketmatic will provide sensible defaults you must specify the name of the widget ticketmatic provides following widgets widgets docid\ xy bxjznntsula bjnc v used for an authenticated buying process widgets docid\ xy bxjznntsula bjnc v used for adding tickets to an order (step 2) widgets docid\ xy bxjznntsula bjnc v used for displaying and optionally modifying an order (step 3) widgets docid\ xy bxjznntsula bjnc v used for checking out an order (step 4) widget authenticate use this widget to enable an authenticated buying process the returnurl will contain the contactid as parameter this widget needs to be used as the first step in the buying process widget addtickets use this widget to add tickets for one or more events to an order you can also use it to add products docid\ biy wkbht2epjzqoaoc37 to an order you should at least specify the event or product parameter in the event parameter, specify one or more event ids (comma separated) for which you want to sell tickets specifying multiple event ids works best when you have only a limited set of prices for each event with too much prices, the widget quickly becomes too complicated in that case it is best to use separate widgets for each event in the product parameter, specify one or more product ids upselling the addtickets widget supports upselling you can specify additional events and products beside the main event or product on sale use the parameters extraevents and/or extratickets and specify one or more ids ticketmatic only supports unseated events in the extraevents parameter collecting ticket info use the ticketinfo parameter to specify what information should be collected for each ticket that was added to the order the ticketinfo parameter should contain a comma separated list of fields if this parameter is not specified, no extra ticket information will be collected supported ticketinfo fields value description name name of the ticket holder email e mail address of the ticket holder example ticketinfo=name,email action after adding tickets use the flow parameter to specify what should happen after adding tickets to the order value description return after adding tickets, go straight back to the website (parameter returnurl decides where the user is redirected to) checkout after adding tickets, go straight to checkout (default) basket after adding tickets, go to the basket page the basket page will contain an 'add more tickets' link and the user will be redirected to the website when clicking this link (parameter returnurl decides where the user is redirected to) basketwithcheckout after adding tickets, go to the basket page with possibility to continue to checkout the basket page will contain an 'add more tickets' link and the user will be redirected to the website when clicking this link (parameter returnurl decides where the user is redirected to) widget basket use this widget to display the contents of the current order to a user disable editing the order you can optionally disable the user to edit his order by specifying value no for the parameter edit if this parameter is not specified, the basket is read only action after displaying the order use the flow parameter to specify what should happen after displaying the order value description return after displaying the order, go straight back to the website (parameter returnurl decides where the user is redirected to) checkout display a checkout button in the basket widget so the user can optionally continue to the checkout widget checkout use this widget to handle checkout of an order this means registering customer, payment and delivery info and handling the online payment use the parameter panels to specify what part of the checkout should be handled the panels parameter should contain a comma separated list of fields if this parameter is not specified, all parts will be handled supported fields value description customer customer registration delivery selection of delivery method payment selection of payment method and handling online payment action after checkout use the oncompletion parameter to specify what should happen after the checkout value description orderdetail after a succesful checkout, go to the ticketmatic order detail page return after a succesful checkout, go back to the website (parameter returnurl decides where the user is redirected to) widget addoptionbundles use this widget to sell one or more option bundles after selecting the product, the user will be asked for its details firstname , lastname , email after which he/she will be able to configure the option bundle by adding tickets use the parameter product to specify the option bundles to sell multiple product ids are supported action after adding tickets use the flow parameter to specify what should happen after adding tickets to the order value description return after adding tickets, go straight back to the website (parameter returnurl decides where the user is redirected to) checkout after adding tickets, go straight to checkout (default) basket after adding tickets, go to the basket page the basket page will contain an 'add more tickets' link and the user will be redirected to the website when clicking this link (parameter returnurl decides where the user is redirected to) basketwithcheckout after adding tickets, go to the basket page with possibility to continue to checkout the basket page will contain an 'add more tickets' link and the user will be redirected to the website when clicking this link (parameter returnurl decides where the user is redirected to) widget subscribe use this widget to let the user fill in his/her details after checkout use the parameter fields to specify the details the user can fill in supported values are customertitle , address , phone , birthdate styling widgets you can style widgets by styling the webskin see the web skins docid\ h dtn0wzgkmqvnzpezjsa article for more details you can define several webskins use the parameter skinid to specify the webskin to use for the widget if this parameter is not specified, the default webskin is used parameter returnurl the parameter returnurl can be used on any widget it should contain the landingpage on the website where the user will be redirected to after finishing the widget when redirecting the user to the landingpage, ticketmatic will add following parameters to the returnurl accesskey the accesskey that was passed in the widget url orderid the orderid used or generated in the widget ordercode an ordercode representing the current active basket contactid the id of the authenticated contact reason the reason why the user was redirected signature ticketmatic generates a signature so you can verify that the call to the returnurl is genuine the parameters are signed in exactly the same way as they need to be signed for the widget url more advanced integration for even more advanced integration, you can combine widgets with the api docid\ ezkoi3hp1oaxeiehyy2gv for example you could use the api to add tickets to the basket, and then use a checkout widget for letting the customer finish his order generating widget urls manually the easiest way to generate a widget url is by using one of the widgets docid\ xy bxjznntsula bjnc v but you can also generate it manually all widgets are provided at the endpoint get https //apps ticketmatic com/widgets/{accountname}/{widgetname}?{parameters} \&accesskey={accesskey} \&signature={signature} {accountname} is the short name for the account you can retrieve this in settings > account parameters {widgetname} is the name of the widget {parameters} contains the set of widget specific querystring parameters {accesskey} is the accesskey used to generate the signature {signature} contains the signature for the request generating a widget signature in order to make sure that the widget urls are not tampered with, you have to generate a signature and add this to each widget url before you can start generating signatures, you will need an api keypair that has sufficient permissions to generate widget signatures more info on obtaining an api key https //www ticketmatic com/docs/api/coreconcepts/authentication/ generating the signature the keypair consists of 2 keys access key this is a public key and is passed in each request secret key this is a private key and is never passed in requests it should be kept secret every request you make to a widget must carry with it the access key and a signature the signature is computed by hashing the request parameters and the access key, using the secret key as hashing key the hashing algorithm used is sha256 in php you would generate the signature as follows $signature = hash hmac( 'sha256' , $accesskey $accountshortname $parameters, $secretkey ); example suppose you want to call the addtickets widget with following parameters event 123 skinid 25 l fr returnurl http //www ticketmatic com http //www ticketmatic com and your keypair is access key azertyuiop secret key qsdfghjklm first, generate the payload for the signature by concatenating these fields accesskey, account shortname, parameter names and values in alphabetical order azertyuiopmyaccountnameevent123returnurlhttp //www ticketmatic comskinid25 remark the l parameter (languagecode) should not be included when generating the signature! then, calculate the signature $signature = hash hmac('sha256' , "azertyuiopmyaccountnameevent123returnurlhttp //www ticketmatic comskinid25", "qsdfghjklm"); this should return 0978f4fb9341ad17f6ed82bb1db0acbc2748b9042f39f10457eaded938fef2b8 the final widget url is https //apps ticketmatic com/widgets/myaccountname/addtickets? event=123& l=fr& returnurl=http%3a%2f%2fwww ticketmatic com\&skinid=25& accesskey=azertyuiop& signature= 0978f4fb9341ad17f6ed82bb1db0acbc2748b9042f39f10457eaded938fef2b8 remark that the parameters in the url should be urlencoded along rfc 3986 (for example the returnurl should be encoded as http%3a%2f%2fwww ticketmatic com) for generating the signature, the original value should be used and not the urlencoded value more information > widget parameter reference docid 2i evsoi3emnewojfd8u2