Embed an OAuth Web Component

Embed code used in sandbox must be changed before being used in production. Some embed parameters, as outlined in the following steps, vary between sandbox and production environments.

Nitro JavaScript Library

The Nitro JavaScript Library is required for all web components. It identifies the web components you want to load and loads them. Do not locally store the library.

For each page where you want to display web components, Nitro JavaScript only needs to be included on the page one time. Once on the page, the script finds your web component embed tags and loads the resources they need to run.

Dynamic Updates

For programs where web components are not regularly refreshed via page navigation, you can use the "update" function to ensure you get the latest data from Nitro. We recommend you leverage this function on components where it's appropriate to get new data in response to a user action. It should not be used to poll our APIs on a timer. Show me example scenarios and code samples

Scenario One: You have a page that contains the Recognitions block and Missions web component and that page is set up so that the user doesn't have to refresh the page (single page app). You have a mission that completes when a recognition is sent. When the user sends a recognition that completes the mission, the mission will remain in the missions list until the page is refreshed. However, if you use the update function on the Missions web component, the user would get the latest eligible missions without a full page refresh.

By selecting the component with JavaScript, you can invoke the update function. This is supported by all web components.

document.querySelector("bunchball-missions").update()

Scenario Two: You have a page that contains the Missions web component and that page is set up so that the Quiz web component is launched from the Missions detail page into a modal overlay. When the user passes a quiz, the task for completing the quiz will remain in the task list as incomplete until the page is refreshed. However, if you use the update function when an event is handled (such as the user closing the modal after completing the quiz), the user would see the completion without a full page refresh. Include as many components that are on your page that would benefit from seeing an update of data.

// When the user clicks on <span> (x), close the quiz modal
span.onclick = function() {
modal.style.display = "none";
document.querySelector("bunchball-missions").update();
document.querySelector("bunchball-profile").update();
document.querySelector("bunchball-events").update();
document.querySelector("bunchball-leaders").update();
}

Embed Steps

The following steps describe a generic overview of embedding OAuth web components. Not all web components produce the same embed code. Follow the specific instructions and tips provided with the web component preview and resulting embed code to embed a web component on your site. To embed a block, see Embed a Block.

1. Use the Web Component Builder to configure, save, and get the embed code for your web component. Note: Embed code is not available until you save the web component.
2. Add the Nitro web component tag on your page in the location where you want the web component to display.
   • For Web Components:
     • Set the web component tag name: bunchball-profile, bunchball-missions, bunchball-events, bunchball-interaction, bunchball-leaders, bunchball-ots, bunchball-quiz, or bunchball-trophy.
     • Where web components support a data-user-id attribute, it should be set, along with using a 3-legged OAuth token.

<bunchball-events style="display:block; width:400px; height:450px;"
    data-token=%oauth_token%
    data-server="https://api.sandbox.bunchball.com"
    data-user-id="AutoTest"
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-custom-css='[""]'>
</bunchball-events>

<bunchball-events style="display:block; width:400px; height:450px;"
    data-token=%oauth_token%
    data-user-id="AutoTest"
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-custom-css=''>
</bunchball-events>

• For iframes
  • Make sure the "name" attribute in the embed code div name matches the name of the web component you created in Nitro Studio. This uses the web component parameters defined in Nitro Studio.
    To bypass pulling the web component data from Nitro Studio, hardcode the name using the data-element-type parameter. Element types include: QUIZ, MINI_PROFILE, EVENTS, MISSIONS, OTS, LEADERS, TROPHY.
  • The "class" attribute allows nitro.js to recognize the tag as a web component embed tag.
  • Where web components support a data-user-id attribute, it should be set, along with using a 3-legged OAuth token.

<div name="Events"
    class="nitro-widget"
    width="400"
    height="450"
    data-user-id="AutoTest"
    data-name='Events'
    data-custom-css='[""]'
    data-embed-type='iframe'
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-width='400'>
</div>

3. You can place text or other content between the opening and closing tags to provide loading text or a loading image until the content loads.
   You can also provide alternate content to display to your users instead of Nitro content. You may want to do this in case the Nitro servers can't be reached. To provide alternate content, use the <nitro:block>, <nitro:content> and <nitro:alt> tags.
4. Add Nitro JavaScript to your page as a direct child of the <body> element or after the </body> tag. You should not nest this script under another element, like a <div>. The code that gets executed upon inclusion appends a new <div> to the <body> tag, which cannot happen from within a nested element. This code only needs to be included on the page once. After adding the script, change the values for your environment.
• web component - Add component.min.js BEFORE all web component elements.

<script src="https://components.bunchball.com/web/latest/component.min.js"></script>

<script src="https://components.bunchball.com/web/v6.1/component.min.js"></script>

• iframe - Add nitro.min.js AFTER all web component tags. You must use an "id" attribute of "nitro-js" as well as the src, and data-token attributes. We also recommend you use a data-version attribute which differs in Sandbox and Production environments.

<script id="nitro-js"
     data-token=%oauth_token%
     data-server="https://api.sandbox.bunchball.com"
     data-version="latest"
     src="https://components.bunchball.com/nitro/latest/nitro.min.js"
     data-custom-css='[""]'></script>

<script id="nitro-js"
     data-token=%oauth_token%
     data-version="v6.1"
     src="https://components.bunchball.com/nitro/v6.1/nitro.min.js"
     data-custom-css=''></script>

Embed Parameters

Example Embed Code

Web Component

<script src="https://components.bunchball.com/web/latest/component.min.js"></script>
<bunchball-events style="display:block; width:400px; height:450px;"
    data-token=%oauth_token%
    data-server="https://api.sandbox.bunchball.com"
    data-user-id="AutoTest"
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-custom-css='[""]'>
</bunchball-events>

<script src="https://components.bunchball.com/web/v6.1/component.min.js"></script>
<bunchball-events style="display:block; width:400px; height:450px;"
    data-token=%oauth_token%
    data-user-id="AutoTest"
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-custom-css=''>
</bunchball-events>

iframe

<HTML>
  <head>
    <title>My Web Component</title>
  </head>
<body>
  <div name="Events"
    class="nitro-widget"
    width="400"
    height="450"
    data-user-id="AutoTest"
    data-name='Events'
    data-custom-css='[""]'
    data-embed-type='iframe'
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-width='400'>   
  <script id="nitro-js"
     data-token=%oauth_token%
     data-server="https://api.sandbox.bunchball.com"
     data-version="latest"
     src="https://components.bunchball.com/nitro/latest/nitro.min.js"
     data-custom-css='[""]'></script>
</body>
</HTML>

<HTML>
  <head>
    <title>My Web Component</title>
  </head>
<body>
  <div name="Events"
    class="nitro-widget"
    width="400"
    height="450"
    data-user-id="AutoTest"
    data-name='Events'
    data-custom-css='[""]'
    data-embed-type='iframe'
    data-export-navigation='false'
    data-return-count='10'
    data-title='Recent Achievements'
    data-width='400'>   
  <script id="nitro-js"
     data-token=%oauth_token%
     data-version="v6.1"
     src="https://components.bunchball.com/nitro/v6.1/nitro.min.js"
     data-custom-css='[""]'></script>
</body>
</HTML>

See also

Styling web components

OAuth Client

Blocks

Web components