Content Picking and Sharing

Prerequisites

• Showpad Ultimate package
• Showpad Administrator or Promoted Member account
• An OAuth client.

This integration is designed to seamlessly embed Showpad within other applications enabling your sales teams to intuitively browse for content, quickly select relevant materials, and share them in just a few clicks. Typical use cases are:

• Inserting a Showpad sharing link into a third party platform for which Showpad doesn't yet provide out-of-the-box integrations.

• Surfacing Showpad content search into your own platforms.

• Embedding a content picker in Showpad Apps.

The content picker for integrations has the same features as it does within the core Showpad platform, allowing the seller to search, browse and navigate Experiences, access their collections or personal content, and more.

Good News!

The picking and sharing integration handles all of the communication with the Showpad API and returns information about the selected files via a JavaScript callback.

Process Overview

In a typical integration, you will host the service on your own servers. The service will:

Step	Description
1.	Obtain the correct Showpad subdomain. This is particularly useful if the integration is to be used by multiple Showpad instances.
2.	Obtain Authentication (i.e., an OAuth access token) For integrations used by multiple Showpad instances, this typically begins with an HTML form where users enter their Showpad subdomain.
3.	Use the Content Picker SDK to render a UI where users can select Showpad content.
4.	Interact with the Showpad API or provide your own asset-based functionality to generate a tracked link of Showpad content to share.

Authentication

A content picker lives in the context of:

• a specific Showpad organization (subdomain)
• a specific user within that organization.

These two elements determine which content to surface to the user.

OAuth Credentials

Your integration must have permission to access your Showpad content. We recommend using OAuth2 with the Authorization Code Flow with a user entering their Showpad subdomain.

note

This OAuth client only requires viewing permissions.

Authorization URL

Within a third-party (e.g., Gong) hosted page, you can load a static Showpad HTML form that submits an authentication URL to your server. This page is typically loaded from a browser popup window.

To submit this form, you must construct a authorization URL containing your client ID and Showpad subdomain.

OAuth, Redirect, and Callback

Step	Description
1.	Open a window. This is typically initiated with a JavaScript window.open method or in an iFrame.
2.	Load the subdomain input page with a form (HTML frontend).
3.	Construct the URL to initiate OAuth flow for the user.
4.	Provide a callback endpoint to catch users returning from OAuth flow and perform a token exchange. We suggest using the OAuth state parameter or some session storing mechanism to ensure the user's authentication information isn't lost and to avoid repeating each time.
5.	Send user-chosen subdomain and obtained access token back to window opener (additional HTML frontend).
6.	The user is directed to Showpad for login and authorization. Once done, the user is returned to your site with an authorization code in the URL.
7.	The third-party host performs an exchange (authentication token and client secret) to get an access token, then sends the subdomain and access token back to the popup page.
8.	Once the subdomain and token are obtained, you can use the content-picking SDK from npm to spawn a content-picker UI.

Content Picker SDK

The Content Picker SDK renders a content picking UI. You can install it into your project from npm:

npm

npm install @showpad/content-picker

yarn

yarn add @showpad/content-picker

pnpm

pnpm install @showpad/content-picker

Once installed, you can then use in your projects:

import "./index.css";
import { Auth, createContentPicker } from "@showpad/content-picker";
// setup DOM
document.querySelector("#root")!.innerHTML = `
<h1>Basic Showpad Plugin</h1>
<section>
<div id="content-picker" class="content">
</div>

<aside>
    <button id="create-share">Create Share</button>
    <h2>Output</h2>
    <pre>{}</pre>
  </aside>
</section>
`;

// Use the following code to use the Auth provider with the Auth Code flow using a Showpad OAuth client
const clientCreds = createClientCredentialsProvider({
  // your Showpad OAuth client credentials
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  // your redirect URi of the OAuth client should match the URL of the page where the content picker is embedded
  redirectUri: "YOUR_APP_URL",
  // name of your Showpad instance
  subdomain: "YOUR_SUBDOMAIN",
});

// Use the following code to use the Auth provider with the Personal Access Token flow
const personalAccessToken = {
  getToken: async () => {
    // use your own personal API token or implement an oauth client auth flow
    return 'ACCESS_TOKEN';
  },
  async getOrgInfo() {
    return {
      subdomain: "YOUR_SUBDOMAIN",
    };
  },
}

// Register Auth Provider
Auth.registerProvider(clientCreds);

function selectShowpadContent() {
  return new Promise(async (resolve) => {
    // Create the content picker
    const contentPicker = await createContentPicker(
      document.getElementById("content-picker")!,
      {
        onSelectAssets: (assets) => {
          contentPicker.close();
          resolve(assets);
        },
        allowMultipleSelection: true,
        language: "en",
        onPreview: (url) => window.open(url, "_blank"),
      }
    );
    // Open the content picker
    await contentPicker.open();
  });
}

const assets = await selectShowpadContent();
console.log(assets);

Showpad API

Once the content picker is in place, you're ready to call the Showpad API to create a Share and enable users to select and share Showpad content.

Content Picker Example

You'll find an example content picker in this GitHub repository.