Amiando Community Ticketing API (Ticket Shop Upgrade)

From Amiando Developer Wiki

Contents 1 What is Community Ticketing? 2 How to get started? 3 Overview 4 Technical details 4.1 Javascript File 4.1.1 Description 4.2 Javascript Object: Getamiando 4.3 JavaScript Methods 4.3.1 amiandoIsTicketShopActive 4.3.2 amiandoEditTicketShop 4.3.3 amiandoShowTicketsOverview 4.3.4 amiandoSynchronizeTicketShop 4.3.5 amiandoIsTicketShopDeletable 4.3.6 amiandoDeleteTicketShop 4.3.7 amiandoTicketShopIFrame 4.3.7.1 Defining colors for the TicketShop 4.3.7.2 Force Logout 4.4 Automatic resizing of the IFrame 5 Complete Integration Examples 5.1 Displaying the Ticketshop 5.2 Adding / Editing the TicketShop 5.3 Synchronizing the TicketShop

What is Community Ticketing?

You have thousands of events in your community. Let your users sell tickets for their events and earn money with every sold ticket. The amiando Community Ticketing API plugs seamlessly into your existing event functionality and upgrades it with an integrated event ticketing solution.

You can find all general, non-tech information at http://www.communityticketing.com

How to get started?

How to get started?

Get an overview about Community Ticketing at http://www.communityticketing.com Have a look at the technical specification on this site Get your developer account via the "Contact us now"-form at http://www.communityticketing.com Our team activates your account and supports you in developing your code

Overview

This document describes the amiando Community Ticketing API. The amiando Community Ticketing API adds ticketing to an existing event function. The interface is based on JavaScript and IFrame technology.

Social network partners are able to upgrade their event functions with a ticketing and online billing service. Users of the partner platform keep using the partner's event function in their usual environment but will also be able to promote their events and sell tickets and/or charge fees for online registration of their attendants.

Technical details

This section will provide more information about the amiando Community Ticketing API

Javascript File

This script contains all ticket shop methods and needs to be included on every page that uses ticket shop functions.

<script language="Javascript"
src="https://subdomain.amiando.com/event/ticketShop.js.html?v=1.0
&eventIdentifier=yourUniqueEventIdentifier
&username=yourUniqueUserIdentifier" type="text/javascript"></script>

Description

Parameter	Description
subdomain	the subdomain information you entered in the partner area.
eventIdentifier	unique identifier for the given event. This identifier should never change for the event. Use for example your internal event ID.
username	unique identifier for your user. This identifier should never change for the user. Use for example your internal user ID or your user’s login name. This parameter is only needed if you use the Single-Sign-On (SSO) module. If you don’t use SSO call the script without this parameter.

Javascript Object: Getamiando

Use this structure to pass information about your event to amiando.

Parameter	Type	Description	Required
title	string	title of the event	always
date	string	date the event takes place, format: Aug 20, 2007 08:00	always
enddate	string	enddate of the event, format: Aug 20, 2007 08:00	optional
organisatorDisplayName	string	name of the organisator, when different from user name	optional
visibility	int	set public events '2', private events '1'	optional
location	string	short name of the place of the event	optional
description	string	the description of the event	optional
category	string	the category of the event, see list of category types	optional
street	string	street address of the event location	optional
city	string	city of the event location	optional
zipCode	string	Zipcode of the event location	optional
country	string	country of the event location (ISO 3166-1 alpha-2 format)	optional
feeInclusive	boolean	Is the amiando fee included in the ticket price? Default: false	optional
salesTax	string	Sales tax (VAT) on the ticket price. The ticket prices are always gross prices. Decimal places are comma separated if needed (Example: "19,6"). Note that each country only allows certain tax rates. Default: 0	optional
commercial	boolean	Is the event commercial? If yes, it requires a "salesTax".	optional
showAvailableTickets	boolean	Should the ticketShop show the still available ticket count? Default: true	optional
partnerEventUrl	string	the url to the event on the partner's website	optional
partnerEmailNotification	boolean	event host receives amiando emails, Default: true	optional
partnerSynchronizationPopup	boolean	true, opens a popup after sychronizing; false: opens a hidden iframe. Default: true	optional

JavaScript Methods

The following section provides a overview of the available javascript function. Note that you have to include the amiando javascript file (described above) to use this functionality. The functions can not be used multiple times on the same webpage. So its not possible to offer several edit buttons at once for different ticketshops.

amiandoIsTicketShopActive

Parameters
None

Return value
Returns true if a ticketshop exists and false if the ticketshop is not activated yet.

Example

<script type="text/javascript">
  if (amiandoIsTicketShopActive()) {
    alert("TicketShop exists");
  }
</script>

amiandoEditTicketShop

Creates/edits a ticket shop. If no ticket shop is associated with the given event a new ticket shop will be created. If a ticket shop for this event exists already, the user can edit the ticket shop settings.

Opens a popup window and shows the amiando wizard where you can create/edit your ticketshop.

Parameters

Parameter	Type	Description	Required
getamiando	object	Array with the eventdata (see section above)	required
callback	function	Callback function which will be called after the editing popup is closed. The function has a boolean parameter which signals if the ticketshop was edited successfully.	optional

Return value
None

Example

<script type="text/javascript">
  getamiando = new Array();
  getamiando["title"] = 'title of your event';
  getamiando["organisatorDisplayName"] = 'name of the organisator of the event';
  getamiando["description"] = 'description of the event';   
  getamiando["date"] = 'date of the event in the format Aug 20, 2007 08:00';
  getamiando["location"] = 'the location where the event will take place';
  getamiando["street"] = 'the street where the event will take place';
  getamiando["city"] = 'the city in which the event will take place';
  getamiando["zipCode"] = 'The zipcode of the eventlocation';
  getamiando["country"] = 'The ISO 2-letter code of the country';
  getamiando["category"] = 'category of your event';
  getamiando["partnerEventUrl"] = 'the url to your event';
  function editCallback(success) {
    if (success) {
      alert("TicketShop was edited successfully.");
      location.reload();
    } else {
      alert("User has aborted while creating the ticketshop.");
    }
  }
</script>
<a href="#" onclick="amiandoEditTicketShop(getamiando, editCallback); return false;">Edit TicketShop</a>

amiandoShowTicketsOverview

Opens a popup containing the overview of tickets for the given event/ticket shop.

Parameters

Parameter	Type	Description	Required
callback	function	Callback function which will be called after the editing popup is closed.	optional

Return value
None

Example without callback

<script type="text/javascript">
  amiandoShowTicketsOverview();
</script>

Example with callback

<script type="text/javascript">
  function callback() {
    alert("The popup was closed.");
  }
  amiandoShowTicketsOverview(callback);
</script>

amiandoSynchronizeTicketShop

Synchronizes an existing event after editing on the partners’ website. This function should be called after every update of event data on the partner platform in order to keep ticket shop information synchronized.

You can control if the synchronization happens in a popup which is shown to the user or if it is done in the background by setting the "partnerSynchronizationPopup" parameter (see above).

Important Notice: You should not navigate away from your page directly. Otherwise the synchronized data might not reach amiando. Instead navigate away by using the callback from the amiandoSynchronizeTicketShop function.

Parameters

Parameter	Type	Description	Required
getamiando	object	Array with the eventdata	required
callback	function	Callback function which will be called after synchronizing is finished. The function has a boolean parameter which signals if the ticketshop was synchronized successfully.	optional

Return value
None

Example

<script type="text/javascript">
  getamiando = new Array();
  getamiando["title"] = 'title of your event';
  getamiando["organisatorDisplayName"] = 'name of the organisator of the event';
  getamiando["description"] = 'description of the event';   
  getamiando["date"] = 'date of the event in the format Aug 20, 2007 08:00';
  getamiando["location"] = 'the location where the event will take place';
  getamiando["street"] = 'the street where the event will take place';
  getamiando["city"] = 'the city in which the event will take place';
  getamiando["zipCode"] = 'The zipcode of the eventlocation';
  getamiando["country"] = 'The ISO 2-letter code of the country';
  getamiando["partnerSynchronizationPopup"] = 'true';
  function syncCallback(success) {
    alert("TicketShop was synchronized successfully.");
    /* Navigate away from your page now by submitting
    * the original form or similar
    */
  }
  amiandoSynchronizeTicketShop(getamiando, syncCallback);
</script>

amiandoIsTicketShopDeletable

Parameters
None

Return value
Returns true if a ticketshop exists and is deletable or false if the ticketshop can not be deleted anymore (e.g. because tickets have already been sold)

Example

<script type="text/javascript">
  if (amiandoIsTicketShopDeletable()) {
    alert("Ticketshop is deletable");

} </script>

amiandoDeleteTicketShop

Deletes an existing TicketShop. Opens a popup window where user can choose to delete the ticket shop or cancel.

Parameters

Parameter	Type	Description	Required
callback	function	Callback function which will be called after deleting is finished. The function has a boolean parameter which signals if the ticketshop was deleted successfully.	optional

Return value
None

Example

<script type="text/javascript">
  function deleteCallback(success) {
    if (success) {
      alert("TicketShop was deleted.");
      location.reload();
    } else {
      alert("User has aborted while deleting.");
    }
  }
</script>
<a href="#" onclick="amiandoDeleteTicketShop(deleteCallback); return false;">Delete TicketShop</a>

amiandoTicketShopIFrame

Integrates the ticket shop as an iframe into the partners' website. The ticket shop IFrame will be inserted into the page at the same location where amiandoTicketShopIFrame is called.

Parameters

Parameter	Type	Description	Required
width	integer	Width of the ticketshop iframe	required
height	integer	Height of the ticketshop iframe	required
additional	string	Additional parameters (like specification of the ticketshop colors)	optional
language	string	Here you can choose the language for your ticketshop (at the moment de (german), en (english), es (spanish) or fr (french) available)	optional

Return value
Integrates an IFrame containing the ticket shop for the given event.

Example

amiandoTicketShopIFrame(625, 300, '', 'de');

Defining colors for the TicketShop

There are two alternative options to customize the look of the integrated ticket shop. The color definitions have to be passed in the "additional" parameter of the amiandoTicketShopIFrame call.

Simple mode:

Parameter	Type	Description	Required
simple_cbox	hex	Background color of the box	optional
simple_ctext	hex	font color of the text within the ticketshop	optional
simple_cborder	string	Color of the main border of the ticketshop	optional

Advanced mode:

Parameter	Type	Description	Required
adv_cbox	hex	Background color of the box	optional
adv_cbox2	hex	Background color of the ticketshop table	optional
adv_cprogress	hex	Color of the main border of the ticketshop	optional
adv_cheader	hex	Second text color for highlighting and headers	optional
adv_ctext	hex	font color of the text within the ticketshop	optional
adv_cborder	string	Color of the main border of the ticketshop	optional
adv_cbordertable	string	Color of the table's border of the ticketshop	optional

Example

amiandoTicketShopIFrame(625, 300, 'simple_cbox=ffffff&simple_ctext=000000&simple_cborder=000000', 'de');

Force Logout

If all users should be logged out before accessing the TicketShop Iframe, an additional parameter „forceLogout=true" can be passed to the amiandoTicketShopIFrame call. If there are other additional parameters used already (like colors), the parameters must be separated by a "&" sign.

Example

amiandoTicketShopIFrame(625, 300, 'forceLogout=true', 'de');

Automatic resizing of the IFrame

If you dont want the iframe to stay at a fixed size (which would display additional scrollbars in the iframe), you can pass an additional resizeIFrame=true parameter to the call of the TicketShop Javascript. The iframe will then automatically adjust its size to the content, so the no additional scrollbars will be shown. This behaviour is off by default.

<script language="Javascript"
src="https://subdomain.amiando.com/event/ticketShop.js.html?v=1.0
&eventIdentifier=yourUniqueEventIdentifier
&username=yourUniqueUserIdentifier
&resizeIFrame=true" type="text/javascript"></script>

Complete Integration Examples

Adapt this code to your community and use it for your integration. These examples show a complete integration.

The values used here are:
subdomain: testcommunity
eventIdentifier: event21372
username: user8384@testcommunity.de

Displaying the Ticketshop

Place this method where your ticket shop should be in your event.

<script language="Javascript" src="https://testcommunity.amiando.com/event/ticketShop.js.html?v=1.0
&eventIdentifier=event21372&username=user8384@testcommunity.de" type="text/javascript"></script>
<script>amiandoTicketShopIFrame(650, 350, , 'de');</script> 

Adding / Editing the TicketShop

The following code snippets can be used to display links or buttons to edit or delete the ticketshop.

<script language="Javascript" src="https://testcommunity.amiando.com/event/ticketShop.js.html?v=1.0
&eventIdentifier=event21372&username=user8384@testcommunity.de" type="text/javascript"></script>
<a href="#" onclick="amiandoEditTicketShop(getamiando, _callback); return false;"
  id="linkEditTS" style="display:none">Edit TicketShop</a>
<a href="#" onclick="amiandoEditTicketShop(getamiando, _callback); return false;"
  id="linkAddTS" style="display:none">Add TicketShop</a>
<a href="#" onclick="amiandoDeleteTicketShop(_callback); return false;"
  id="linkDeleteTS" style="display:none">Delete TicketShop</a>
<a href="#" onclick="amiandoShowTicketsOverview(); return false;"
  id="linkViewTickets" style="display:none">Overview of the tickets</a>
<script type="text/javascript">
  getamiando = new Array();
  getamiando["title"] = 'title of your event';
  getamiando["organisatorDisplayName"] = 'name of the organisator of the event';
  getamiando["description"] = 'description of the event';
  getamiando["date"] = 'date of the event in the format Aug 20, 2007 08:00';
  getamiando["location"] = 'the location where the event will take place';
  getamiando["street"] = 'the street where the event will take place';
  getamiando["city"] = 'the city in which the event will take place';
  getamiando["zipCode"] = 'The zipcode of the eventlocation';
  getamiando["country"] = 'The ISO 2-letter code of the country';
  getamiando["category"] = 'category of your event';
  getamiando["partnerEventUrl"] = 'the url to your event';
  /* The callback which reloads the current page to reflect
   * the changes in the page */
  function _callback(success) {
    if (success) {
      location.reload();
    }
  }
  /* Now display the correct links depending on the current
   * state of the ticketshop */
  if (amiandoIsTicketShopActive()) {
    document.getElementById("linkEditTS").style.display = "block";
    document.getElementById("linkViewTickets").style.display = "block";
  } else {
    document.getElementById("linkAddTS").style.display = "block";
  }
  if (amiandoIsTicketShopDeletable()) {
    document.getElementById("linkDeleteTS").style.display = "block";
  }
</script>

Synchronizing the TicketShop

The following code snippets can be used to update the ticketshop information after the event data has been edited on your page.

<script language="Javascript" src="https://testcommunity.amiando.com/event/ticketShop.js.html?v=1.0
&eventIdentifier=event21372&username=user8384@testcommunity.de" type="text/javascript"></script>
<a href="#" onclick="amiandoSynchronizeTicketShop(getamiando, syncCallback); return false;">Save your event changes</a>
<script type="text/javascript">
  getamiando = new Array();
  getamiando["title"] = 'New title of your event';
  getamiando["organisatorDisplayName"] = 'New name of the organisator of the event';
  getamiando["description"] = 'New description of the event';   
  getamiando["date"] = 'New date of the event in the format Aug 20, 2007 08:00';
  getamiando["location"] = 'the new location where the event will take place';
  getamiando["street"] = 'the new street where the event will take place';
  getamiando["city"] = 'the new city in which the event will take place';
  getamiando["zipCode"] = 'The new zipcode of the eventlocation';
  getamiando["country"] = 'The new ISO 2-letter code of the country';
  getamiando["partnerSynchronizationPopup"] = 'true';
  /* Navigate away from your page now by submitting
   * the original form or similar
   */
  function syncCallback(success) {
    document.getElementById("originalForm").submit();
  }
</script>