Docs
Launch GraphOS Studio

Embedding the Explorer

You can embed the GraphOS Studio Explorer in a webpage that you can then provide to your graph's consumers. This enables those consumers to test out s from your own website.

For example, here's an embedded for an Apollo example graph. Try it out!

Embedding on the Apollo Server landing page

In Apollo Server v3.8.0 and later, you can use a built-in plugin to embed the directly on your server's landing page.

You use the ApolloServerPluginLandingPageLocalDefault plugin to configure the landing page in your local development environment, and you use ApolloServerPluginLandingPageProductionDefault for production environments:

import {
  ApolloServerPluginLandingPageLocalDefault,
  ApolloServerPluginLandingPageProductionDefault 
} from '@apollo/server/plugin/landingPage/default';


let plugins = [];
if (process.env.NODE_ENV === 'production') {
  plugins = [ApolloServerPluginLandingPageProductionDefault({ embed: true, graphRef: 'myGraph@prod' })]
} else {
  plugins = [ApolloServerPluginLandingPageLocalDefault({ embed: true })]
}


const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins
});

For more information, see the landing page plugin API reference.

Embedding on an arbitrary webpage

  1. Open GraphOS Studio and select the graph you want to use with the embedded .

  2. Go to the 's page.

  3. Under the 's Settings tab, find Embed Explorer and click Copy code snippet.

    The following dialog appears:

    Explorer embed dialog

  4. Use the options on the left side of the dialog to customize the embedded 's appearance and behavior to your liking.

  5. Still in the dialog, use the tabs above the code snippet to select the snippet for your use case:

    • Use React for React apps where you can npm install the @apollo/explorer package. You will need to install the optional dependency use-deep-compare-effect to use the React package.
    • Use JavaScript for non-React JavaScript apps where you can npm install the @apollo/explorer package.
    • Use Built file on CDN to use Apollo's CDN-hosted embedded .

  6. Click Copy to copy the snippet, then paste it into your code.

For descriptions of options shown in the dialog (along with advanced options that aren't shown), see below.

Setting a default operation

You can prepopulate your embedded with an from one of your existing Explorer tabs. If you do, the embedded Explorer includes all of the following automatically on load:

  • The you selected
  • Any names and values defined in the 's associated tab that are used by the
  • All header names and values defined in the 's associated tab

To prepopulate a default , use one of the following methods:

Option 1

Open the ••• menu next to an and click Embed this operation:

Explorer embed link

Option 2

Open the share dropdown in the and select Share as embed:

Explorer embed dropdown

Authorization

If you're embedding a public variant, anyone with access to the embedded can view your and make queries against your .

If you're embedding a private variant, the embedded first asks users to authenticate by signing in to Studio. Authenticated users are then asked to authorize their Studio account to be used on the embedding webpage:

Explorer authorization screen

After authorizing, users can access the embedded , which includes navigation and visible collections.

Options

The EmbeddedExplorer object takes an options object with the following structure (individual options are described below):

{
  graphRef: 'acephei@current',
  endpointUrl: 'https://acephei-gateway.herokuapp.com',
  persistExplorerState: false,
  initialState: {
    document: `query ExampleQuery {
  me {
    id
  }
}
`,
    variables: { 'Variable1': 'ExampleValue' },
    headers: { 'Header1': 'ExampleValue' },
    displayOptions: {
      showHeadersAndEnvVars: true,
      docsPanelState: 'open',
      theme: 'light',
    },
  },
  handleRequest: (endpointUrl, options) => {
    return fetch(endpointUrl, {
      ...options,
      headers: {
          ...options.headers,
          authorization: `token ${token}`
      },
    })
  },
}

Top-level options

These are the top-level s you can include in the options object you pass to new EmbeddedExplorer:

Name /
Type		Description
graphRef

string

Required. The for the you want to use the embedded with. Has the format graph-id@variant-name. This value is automatically populated in the 's embed snippet.

The fetches this 's from Studio to populate its Documentation panel and enable code completion.

If you omit this option, the does still load, but it doesn't know which to fetch. This prevents the from providing critical features like documentation and code completion.

endpointUrl

string

The endpoint URL of the you want to use the embedded with. This value is automatically populated in the Explorer's embed snippet.

Required, unless you specify your own fetcher with the handleRequest option.

autoInviteOptions

{ accountId: string; inviteToken: string; }

If the graph you are embedding is a private variant, we will by default only allow folks in your org to see the embedded . You can specify that you want anyone who visits your embedded Explorer to be automatically invited to your org with this config object. When you are grabbing the embed code from the Explorer settings in Studio, you have the option to select the role you want folks to be invited as, and the inviteToken and accountId will automatically populate.

If the graph you are embedding belongs to an SSO organization, folks will be able to log in with their SSO account and are automatically invited as the role you specify in the Org Settings page in Studio. Passing this in the embed config for a graph that belongs to an SSO account will not change any behavior. New users to your organization will always be invited as the role you specify in the Org Settings page in Studio.

persistExplorerState

true | false

If true, the embedded uses localStorage to persist its state (including s, tabs, s, and headers) between user sessions. This state is automatically populated in the on page load.

If false, the embedded loads with an example query based on your (unless you provide document).

The default value is false.

handleRequest

(url, options) => Promise

By default, the embedded uses the fetch API to send requests to your endpointUrl. You can instead pass a custom fetcher that's used to run all s.

You might want to do this if you need to include specific headers in every request made from your embedded .

includeCookies

boolean

By default, the embedded uses your 's Include cookies setting, which you configure from the non-embedded in Studio.

You can set includeCookies to true if you instead want the to pass { credentials: 'include' } for its requests.

If you pass the handleRequest option, this option is ignored.

Read more about the fetch API and credentials here.

This config option is deprecated in favor of configuring the Include cookies setting for your in the non-embedded .

initialState

Object

An object containing additional options related to the state of the embedded on page load.

For supported subs, see initialState options.

initialState options

These are the s you can include in the initialState option you pass to new EmbeddedExplorer:

Name /
Type		Description
document

string

A URI-encoded to populate in the embedded 's editor on load.

If you omit this option, the initially loads an example query based on your .

If you use one of the sharing methods described in Setting a default operation, the generated code snippet automatically sets this option with the details of the you used.

If persistExplorerState is true and you provide this option, the loads any of the user's tabs from localStorage, and it also opens a new tab with this .

Example:

intialState: {
  document: `
  query ExampleQuery {
    books {
      title
    }
  }
`;
}
variables

string

A URI-encoded, serialized object containing initial values to populate in the on load.

If provided, these s should apply to the initial query you provide for document.

Example:

intialState: {
  variables: {
    userID: "abc123"
  },
}
headers

string

A URI-encoded, serialized object containing initial HTTP header values to populate in the on load.

Example:

initialState: {
  headers: {
    authorization: 'Bearer abc123';
  }
}
collectionId / operationId

string

The ID of a collection, paired with an ID to populate in the on load. You can find these values in your Studio Explorer by clicking the ... menu next to an you want to embed and selecting View operation details.

Example:

initialState: {
  collectionId: 'abc1234',
  operationId: 'xyz1234'
}

displayOptions options

These are the s you can include in the initialState.displayOptions option you pass to new EmbeddedExplorer:

Name /
Type		Description
docsPanelState

"open" | "closed"

If open, the 's Documentation panel (the left column) is initially expanded. If closed, the panel is initially collapsed.

The default value is open.

showHeadersAndEnvVars

true | false

If true, the embedded includes the panels for setting request headers and environment variables. If false, those panels are not present.

The default value is true.

theme

"dark" | "light"

If dark, the 's dark theme is used. If light, the light theme is used.

The default value is dark.

Previous
Connecting and authenticating
Next
Operation collections
Edit on GitHubEditForumsDiscord