Performer App SDK

Performer App SDK

List your shows, sell tickets, show who performs and grow your mailing list, on your own website. The SDK talks to Performer App for you, from any site, without any server of your own.

Getting started

  1. In Performer App, open Actions, choose Add an action → Web, and pick the universe, venue or show the website is for.
  2. List the websites allowed to use it, and create the key. It looks like pa_pk_….
  3. Add the snippet to your site.
<script src="https://sdk.performer.app/v1.0.0/sdk.js"></script>
<script>
  const sdk = new PerformerAppSDK("pa_pk_your_key");

  sdk.ShowPerformance.listUpcomingByEnvironment("comedy.performer.app")
    .then(({ showPerformances }) => console.log(showPerformances));
</script>

/v1.0.0/sdk.js is pinned: it always behaves exactly as 1.0.0 did, with the latest fixes underneath. new PerformerAppSDK(key) gives you the 1.0.0 methods only.

As a module

import PerformerAppSDK from "https://sdk.performer.app/v1/sdk.mjs";

const sdk = new PerformerAppSDK("pa_pk_your_key");

With npm

Pin a version in code and still get the latest bundle, in the browser or on a server:

npm install @performerapp/sdk-versioned
import { loadPerformerAppSDK } from "@performerapp/sdk-versioned";

const sdk = await loadPerformerAppSDK({ apiKey: "pa_pk_your_key", version: "1.0.0" });

Your SDK key

Every call carries your key, so you can see how much your site uses Performer App: the Web connection in Actions shows the calls of the last 30 days. Without a valid key the SDK doesn't start.

  • Allowed websites. A key works on the sites you list and their subdomains (example.org covers www.example.org and tickets.example.org). With no sites listed it works anywhere. Keys are public, they end up in your page's source, so list your sites.
  • Pausing the Web connection stops the key until you resume it. Removing it stops the key for good.
  • On a server (Node, Bun, Deno) the allowed websites don't apply: there is no browser to say which site is calling.

How requests work

In a browser, on a site that isn't Performer App, the SDK avoids cross-origin restrictions entirely:

  • Reads are JSONP: a script tag whose answer calls back into the SDK.
  • Writes (orders, sign-ups, analytics) are simple requests: plain text, no custom headers, no cookies. Browsers send them without a preflight.

Both carry the key in the address. On a server, everything is a normal fetch with the key in the Authorization header. Either way you call the same methods and get the same results.

If your site has a Content Security Policy, allow https://sdk.performer.app and https://api.performer.app in script-src, and https://api.performer.app in connect-src.

Options

const sdk = new PerformerAppSDK("pa_pk_your_key", {
  // "production" (the default on any real website) or "development",
  // which talks to a Performer App running on localhost.
  environment: "production",
});

Errors

Methods return promises. When Performer App refuses a call, the promise rejects with its answer, usually { validationErrors: [{ field: "CODE" }] }. When the network fails, it rejects with an Error.

AnswerMeaning
{ sdkKey: "INVALID" }The key doesn't exist, or was removed.
{ sdkKey: "PAUSED" }The Web connection is paused.
{ sdkKey: "DOMAIN_NOT_ALLOWED" }This website isn't one of the key's allowed websites.
{ request: "TOO_MANY_REQUESTS" }Slow down: rate limited.
{ … : "NOT_FOUND" }What you asked for doesn't exist (or isn't public).
try {
  await sdk.MailingList.subscribe({ email });
} catch (error) {
  const [first] = error.validationErrors ?? [];
  console.error(first ?? error);
}

ShowPerformance

Upcoming dates of shows, with everything needed to list them: the show's details, its line-up, its venue, and links to buy tickets or ask to perform.

ShowPerformance.listUpcomingByEnvironmentsince 1.0.0

listUpcomingByEnvironment(environmentDomain: string): Promise<{ showPerformances, profiles, venues }>

Every upcoming date of every active show in a universe, soonest first.

ParameterTypeDescription
environmentDomainstringThe universe's domain, e.g. "comedy.performer.app" or your own domain if you connected one.

Returns showPerformances: one entry per date, with the show's fields merged in (title, description, image, coverImage, genres, ...), the date's own (id, startTimeUnixTs, endTimeUnixTs, venueId, lineUp), and ticketLink, performLink, formattedDate and formattedTime (in the venue's time zone). profiles and venues are keyed by id, for the line-up and the venue of each date.

const { showPerformances, profiles, venues } =
  await sdk.ShowPerformance.listUpcomingByEnvironment("comedy.performer.app");

for (const date of showPerformances) {
  const venue = venues[date.venueId];
  console.log(`${date.title} · ${date.formattedDate} ${date.formattedTime} · ${venue.name}`);
  console.log("Tickets:", date.ticketLink);
  console.log("Line-up:", date.lineUp.map(({ profile }) => profiles[profile]?.name));
}

ShowPerformance.listUpcomingByVenuesince 1.0.0

listUpcomingByVenue(venueId: string): Promise<{ showPerformances, profiles, venues }>

Every upcoming date at one venue, whichever universe its show belongs to. Same shape as listUpcomingByEnvironment.

ParameterTypeDescription
venueIdstringThe venue's id.

Returns The same as listUpcomingByEnvironment.

const { showPerformances } =
  await sdk.ShowPerformance.listUpcomingByVenue("venue_123");

document.querySelector("#agenda").innerHTML = showPerformances
  .map((date) => `<li><a href="${date.ticketLink}">${date.title}</a> · ${date.formattedDate}</li>`)
  .join("");

Ticketing

Ticket types, prices and orders. Free tickets are issued straight away; paid ones come back with what Stripe needs to take the payment.

Ticketing.getOptionsForShowPerformancesince 1.0.0

getOptionsForShowPerformance({ showId, performanceId }): Promise<TicketOption[]>

The ticket types on sale for one date.

ParameterTypeDescription
showIdstringThe show's id.
performanceIdstringThe date's id (id of a show performance).

Returns Ticket options: id, title, price (amount, currency), available and restrictions (minPerOrder, maxPerOrder, when sales open and close).

const options = await sdk.Ticketing.getOptionsForShowPerformance({
  showId: "show_123",
  performanceId: "performance_456",
});

for (const option of options) {
  console.log(option.title, option.price.amount, option.price.currency);
}

Ticketing.quoteOrdersince 1.0.0

quoteOrder({ showPerformanceId, tickets, discountCode? }): Promise<Quote>

What a selection costs, with fees and discounts worked out by Performer App. Use it to show a total before the buyer commits.

ParameterTypeDescription
showPerformanceIdstringThe date's id.
ticketsRecord<string, number>How many of each ticket option, by option id.
discountCodestring?A discount code the buyer entered.

Returns { subtotalInCents, discountInCents, feeInCents, totalInCents, currency }.

const quote = await sdk.Ticketing.quoteOrder({
  showPerformanceId: "performance_456",
  tickets: { general: 2 },
  discountCode: "FRIENDS",
});

console.log(`Total: ${(quote.totalInCents / 100).toFixed(2)} ${quote.currency}`);

Ticketing.createOrdersince 1.0.0

createOrder({ fullName, email, tickets, comments, showPerformanceId, discountCode?, platform?, locale? }): Promise<OrderResult>

Places an order. A free order is fulfilled when this resolves, and the buyer gets their tickets by email. A paid one returns the Stripe details to collect the payment with Stripe's own UI.

ParameterTypeDescription
fullNamestringThe buyer's name.
emailstringWhere the tickets are sent.
ticketsRecord<string, number>How many of each ticket option, by option id.
commentsstringA note for the organiser; may be empty.
showPerformanceIdstringThe date's id.
discountCodestring?A discount code.
platform"web" | "ios" | "android" | "windows" | "macos"Where the order is placed. Defaults to "web".
locale"en" | "fr" | "it" | "ru" | "es" | "ca" | "nl"The language of the confirmation email. Defaults to English.

Returns { type: "free", orderId } or { type: "paid", orderId, paymentDetails: { stripePublicKey, stripeConnectAccount, stripeClientSecret } }.

The Stripe key and account are per order: every universe sells through its own Stripe account.

const order = await sdk.Ticketing.createOrder({
  fullName: "Ada Lovelace",
  email: "ada@example.org",
  tickets: { general: 2 },
  comments: "",
  showPerformanceId: "performance_456",
});

if (order.type === "paid") {
  const { stripePublicKey, stripeConnectAccount, stripeClientSecret } = order.paymentDetails;
  const stripe = Stripe(stripePublicKey, { stripeAccount: stripeConnectAccount });
  // Mount Stripe's Payment Element with stripeClientSecret and confirm the payment.
}

Ticketing.createFreeRsvpsince 1.0.0

createFreeRsvp({ fullName, email, tickets, comments, showPerformanceId, platform?, locale? }): Promise<string>

Reserves free tickets and returns the order id. Refuses anything with a price, so a site that only handles RSVPs can't take an order it never collects.

Returns The order id.

const orderId = await sdk.Ticketing.createFreeRsvp({
  fullName: "Ada Lovelace",
  email: "ada@example.org",
  tickets: { rsvp: 1 },
  comments: "Bringing a friend",
  showPerformanceId: "performance_456",
});

Profile

Public profiles of performers, agencies and organisers.

Profile.getByUserNamesince 1.0.0

getByUserName(userName: string): Promise<{ profile }>

A profile by its user name, as in performer.app/@userName.

Returns { profile } with name, bio, avatar, coverImage, socials and more. Images are stored values: pass them through Image.getUrl.

const { profile } = await sdk.Profile.getByUserName("janestandup");
avatar.src = sdk.Image.getUrl(profile.avatar, { width: 96, height: 96 });

Profile.getByDomainsince 1.0.0

getByDomain(domain: string): Promise<{ profile }>

The profile that owns a domain, for a performer's own website.

Returns The same as getByUserName.

const { profile } = await sdk.Profile.getByDomain(location.hostname);
document.title = profile.name;

Venue

Venues and who performs there.

Venue.getByIdsince 1.0.0

getById(venueId: string): Promise<Venue>

A venue's public details.

Returns The venue: name, description, location (address and coordinates), capacity, timeZone, avatar, coverImage, website and more.

const venue = await sdk.Venue.getById("venue_123");
console.log(venue.name, venue.location.streetAddress);

Venue.listPerformerssince 1.0.0

listPerformers(venueId: string): Promise<Performer[]>

Everyone who has performed at the venue, most performances first.

Returns { id, userName, name, avatar, bio, performanceCount, lastPerformedUnixTs }[].

const performers = await sdk.Venue.listPerformers("venue_123");
const wall = performers.slice(0, 12).map((performer) => ({
  name: performer.name,
  photo: sdk.Image.getUrl(performer.avatar, { width: 160, height: 160 }),
}));

MailingList

Sign-ups for a universe's or a venue's mailing list.

MailingList.subscribesince 1.0.0

subscribe({ email, venueId?, locale?, clientIp? }): Promise<{ status: "confirmation_pending" }>

Double opt-in: the person gets an email with a link, and is only added once they follow it. Answers the same whether the address was new, already on the list or recently asked, so a form can't reveal who is subscribed.

ParameterTypeDescription
emailstringThe address.
venueIdstring?A venue's list. Without it, the list of the key's universe. A venue's key always signs up to that venue.
localestring?The confirmation email's language. English by default.
clientIpstring?Calling from your own server? The visitor's IP, or every visitor shares your server's rate limit.

Returns { status: "confirmation_pending" }.

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  await sdk.MailingList.subscribe({ email: form.email.value, locale: "en" });
  form.innerHTML = "Check your inbox to confirm.";
});

Analytics

Counts visits to show pages on your site in the organiser's show analytics. Anonymous: nothing identifies the visitor, and nothing goes to ad platforms.

Analytics.trackShowPagesince 1.0.0

trackShowPage({ performanceId, page, event, durationMs?, sawShowPage? }): Promise<void>

Counts a view, a stay, a share or a purchase.

ParameterTypeDescription
performanceIdstringThe date the page is about.
page"show" | "tickets"The show's own page, or its tickets page.
event"view" | "leave" | "share" | "purchase"What happened.
durationMsnumber?On "leave": how long the page was open. Capped at 30 minutes.
sawShowPageboolean?On "purchase": whether the visitor saw the show page first.

Returns Nothing.

const openedAt = Date.now();
sdk.Analytics.trackShowPage({ performanceId, page: "show", event: "view" });

addEventListener("pagehide", () => {
  sdk.Analytics.trackShowPage({
    performanceId,
    page: "show",
    event: "leave",
    durationMs: Date.now() - openedAt,
  });
});

Image

Images come from the API as stored values. This turns them into urls at the size you show them, served from Performer App's image CDN.

Image.getUrlsince 1.0.0

getUrl(image: string | null | undefined, size?: { width?, height? }): string | null

A url for an image the API returned (avatar, coverImage, image, ...). Sizes are CSS pixels: the CDN serves double for sharp screens. Urls from elsewhere come back unchanged; an empty value gives null. Runs locally: no request, no key needed.

Returns A url, or null.

const src = sdk.Image.getUrl(date.image, { width: 320, height: 320 });
if (src) img.src = src;

Versions

Versions are contracts: a pinned version keeps answering exactly as it did, for as long as it is supported, while fixes reach everyone. New methods only appear in new versions.

VersionScriptWhat changed
1.1.0 (latest)/v1.1.0/sdk.js
  • Spots.find: shows looking for performers, near a city.
  • Browser calls go through JSONP (reads) and simple requests (writes), so the SDK works on any website without CORS setup.
  • An SDK key is required. Create one in Performer App under Actions → Web.
1.0.0/v1.0.0/sdk.js
  • Shows, tickets, profiles, venues, mailing lists, analytics and images.
1.x/v1/sdk.jsAlways the latest 1.x.