Overview of the Embed API
The Embed API allows you to embed certain content from Plug.events into your own site. The process of embedding is based on tokens, where each token corresponds to a search result in a space, with optional filters. For example you can get a token that corresponds to all Salsa dance events in France for the next 15 days. When you use the token to embed those results on your own site, your visitors will see the upcoming Salsa dance events in France.
You must have an organization on Plug.events to use the feature. Create one from the Create menu if needed.
How to set up a token
1. First use Plug.events to search for events. Specifically:
- The search must use an interest or a place, and cannot be anything anywhere. (It can be anything in a certain place, or an interest anywhere.)
- If a geographic search suits you better, first search at the city level then choose Search Nearby.
2. Once you have the results showing (either a direct search on a space or a Search Nearby), press Share, then press “Embed in your web site”.
3. In the next screen, choose your organization and enter the request, explaining briefly where you will be embedding content. Press Request Embed Token.
4. It will take some time to process the request, and we will email you when it is approved.
5. After it is approved, go to manage.plug.events, select the same organization, then navigate to the API Embed Tokens page.
6. Press Edit (next to your token), and update any of the settings:
- Webmaster status: You must set it to Active to be able to use the token
- Output format: Choose the output that best suits your needs. More information on each format is shown below.
- Timezone: Ensure the timezone is appropriate for your viewers. Note that we are only showing dates, but the timezone can still affect which day is displayed.
7. Once you save the token, you will see instructions for using it. You can return to the instructions later from the Use Token button.
HTML Page option
When you select HTML Page as the output format, we will produce the page for you. This is the simplest option. You can set up your site in one of two ways:
- A simple link, which opens the listing in a new page. This is not very useful because you can also just send users to see the list on Plug.events, but you can at least use this to check how it will look when embedded.
- An iframe, which allows content from another site to appear on your page. The iframe code is given to you in the instructions.
When using an iframe, feel free to change the styling. The sample given shows “width:80%;height:400px”, and you can change the width to a different percent, or to a number like 340px, so that the iframe size fits where you need on your page layout.
HTML Fragment option
When you select HTML Fragment as the output format, we will produce the styled page fragment for you, and then you write code to put that fragment anywhere on your page. This involves some javascript code, but has some advantages:
- You can override the default styles to match those on your page
- You can flow the content around images and other elements on the page, instead of being constrained to an iframe rectangle with a scroll bar.
To override styles, you will need a background in CSS:
- Use your browser’s developer tools to inspect the fragment. Notice that there is a <style> element which contains our default styles, followed a div element with class=”plug-root”.
- Check the class names used in the fragment. Some of them are plug-event, plug-event-name, and plug-event-venue.
- Add styles to your page after the ones defined in the fragment.
JSON option
The JSON option is the most developer-friendly, since the data come to you as a javascript array, and you can use the data values to format output as you like. Note that our terms of use require that you display the results, and not store them.
The JSON object is defined like this:
//typescript type
interface Root {
events: {
status - a code indicating cancelation status. 5=live, 9=canceled
createdAt - the ISO formatted date in UTC when the event was created
modifiedAt - the ISO formatted date in UTC when the event was last modified
slug: string, //unique event identifier (normally not displayed)
name: string, //event name
description: string, //event description
bannerImage: string|null, //URL of the banner image, if any
isExpanded: boolean, //true if this is a primary result, recommending the image be displayed
plugUrl: string, //URL to view the event detail on Plug.events
timeDisplay: string|null, //displayable date
startDateTimeIso: string, //start date-time in ISO format, UTC timezone
endDateTimeIso: string, //end date-time in ISO format, UTC timezone
timezone: string|null, //IANA timezone code for the event
isAllDay: boolean, //if true, the time portion of the start/end times should be ignored
publishedByName: string|null, //name of publishing organization
publishedByOrgSlug: string|null, //identifier of publishing organization
priceDisplay: string|null, //displayable price or price range with currency symbol
isFree: boolean, //true means it is a free event
currency: string|null, //symbol for the currency, such as '$'
lowPrice: number|null, //low price if known
highPrice: number|null, //high price if known
venueAddress: string|null, //address
venueLocale: string|null, //structured place name of venue
venueName: string|null //venue name
eventFormat - the code for the event type
eventFormatDisplay - the English text for the event type
}[],
eventListUrl: string, //URL to send users to see the full list on Plug.events
plugLogoUrl: string, //Plug logo, required to display
poweredByMessage: string //powered by message, required to display
}