> For the complete documentation index, see [llms.txt](https://speaking-test-docs.speechace.com/speechace-speaking-test/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://speaking-test-docs.speechace.com/speechace-speaking-test/speechace-workspaces-create-manage-and-share-speaking-assessments/embedding-assessments-in-other-apps-and-websites/oembed-integration-for-speechace-speaking-test.md).
# oEmbed integration for Speechace speaking test
### Overview
oEmbed is a protocol for allowing a **secure** embedded representation of an app in to another app or website. It is a simple way to share media and other rich content from one site to another, without the need for any custom coding or complicated API integrations. With Speechace's oEmbed integration, website owners can easily add the [Speechace speaking test](https://speaking-test-docs.speechace.com/speechace-speaking-test/speechace-workspaces-create-manage-and-share-speaking-assessments/embedding-assessments-in-other-apps-and-websites/www.speechace.com/speaking-test) directly into their own website pages. This allows users to consume the speaking test within the website, without ever leaving it or having to create an account in Speechace's speaking test portal.
Speechace's oEmbed integration also allows website owners to ***optionally*** specify user specific parameters such as User ID, User Full Name and User E-mail. If these parameters are specified in the oEmbed calls to Speechace then they will be visible in various reports generated in the Speechace workspaces.
Last but not the least, website owners can use Speechace's oEmbed integration to specify a [call back URL](#receiving-test-results-on-specified-callback) to save the speaking score in to their own databases.
### oEmbed integration steps
Now, let's review the steps to use oEmbed to integrate Speechace speaking tests in to your own website:
a. First of all create an assessment in your workspace by either [cloning](/speechace-speaking-test/speechace-workspaces-create-manage-and-share-speaking-assessments/creating-assessments/clone-assessments.md) or creating a [custom assessment](/speechace-speaking-test/speechace-workspaces-create-manage-and-share-speaking-assessments/creating-assessments/custom-assessments.md). Let's say, I created a new Call center LV-426 test as shown below.
\
b. Now click on the Share Assessment icon
\
c. Now, you should see the Share Assessment panel pop up as below. Once the popup is available, please click on the oEmbed tab:
\
Now click on the copy link button to get the URL. **Note that the URL has a secret key embedded towards the end and you must protect this key.**
\ **If the key is leaked then anyone will be able to access the test and any usage will be billed to your account.**
d. Now you have to use this URL from your app's backend code using a platform/tool such as cURL, Python, PHP or .Net to obtain an authenticated iFrame code snippet that you can render in your app's front-end. **Note that the following steps must be implemented in your backend code and the oEmbed URL must never be shared or used in front-end.**
To keep things platform neutral, let's see how we can do this from cURL:
Let us say in your system you have a user with the following details:
**UserID: 1234a**\
**User full name: Jackson Sunny**\
**User e-mail: **\
\
Also let's assume that you have set up a **callback URL** wherein the test results can be submitted grades for your user as follows:\
\
\*\*
\
Notice that you can add any parameters to the URL and the parameters will be passed as is to your backend.
Now set up a few parameters for cURL as follows:\
format=json\
app\_user\_id=**1234a**\
app\_user\_email=****\
app\_user\_fullname=**Jackson Sunny**\
app\_score\_submission\_url=****
Now url encode the app\_user\_fullname and the app\_score\_submission\_url using any suitable utility (***URL encoding is important if you have fields with spaces or you are passing the callback URL.)***:
{% hint style="info" %}
**Note for PHP developers on callback URL**\
While encoding the callback URL, PHP devs need to make sure that slashes '/'s are **NOT** encoded and therefore use code as below to restore any encoded slashes '/'s back to the '/' character:\
\
$app\_score\_submission\_url = ''\
$app\_score\_submission\_url = urlencode($app\_score\_submission\_url);\
$app\_score\_submission\_url = str\_replace("%2F", "/", $app\_score\_submission\_url);
{% endhint %}
app\_user\_fullname=Jackson%20Sunny\
app\_score\_submission\_url='https%3A//e-learning-website.com/submit\_speechace\_scores%3Fcourseid%3D91%26testid%3D25%26userid%3D1234a'\
\
Now compose the GET URL query string using the above parameters as below:\
\ app\_user\_id=1234a**&**app\_user\_email=**&**app\_user\_fullname=Jackson%20Sunny\ **&**app\_score\_submission\_url=https%3A//e-learning-website.com/submit\_speechace\_scores%3Fcourseid%3D91%26testid%3D25%26userid%3D1234a
Now combine the url encoded string with the oEmbed URL obtained from the share assessment modal above to create a **GET** query as below:
**&**app\_user\_id=1234a**&**app\_user\_email=**&**app\_user\_fullname=Jackson%20Sunny**&**app\_score\_submission\_url=https%3A//e-learning-website.com/submit\_speechace\_scores%3Fcourseid%3D91%26testid%3D25%26userid%3D1234a
Now call cURL using the **GET** query as follows:
**`curl "`**`https://speak.speechace.co/embed/oembed`**`?`**`url=https%3A%2F%2Fspeak.speechace.co%2Fplacement%2Fapi%2Fcourse%2F108%2F&key=IlYq1zwpMrCaUAW3`**`&`**`app_user_id=1234a`**`&`**`app_user_email=jack@sunny.com`**`&`**`app_user_fullname=Jackson%20Sunny`\
\&#xNAN;**`&`**`app_score_submission_url=https%3A//e-learning-website.com/submit_speechace_scores%3Fcourseid%3D91%26testid%3D25`**`"`**
If the above command is successful, you should see a json response as below:
{% code overflow="wrap" %}
```json
{
"version":"1.0",
"type":"rich",
"provider_name":"Speechace",
"provider_url":"https://speak.speechace.co",
"width":"100%",
"height":"100%",
"title":"Call center LV-426",
"html":""
}
```
{% endcode %}
You can now take the iframe snippet in the html code and pass it to your front end code for embedding. For quick testing, you can replace the iframe snippet in the example HTML below and launch the HTML in to your desktop browser:
{% hint style="info" %}
Note that it is imperative to add the *viewport* meta tag to your HTML file header for proper viewing on mobile:
\\
\
Also note that the above iframe is only valid for 24 hours and therefore you should fetch it just in time instead of caching it.
{% endhint %}
Upon launching the above HTML, the test will launch in an iframe as below:
\
Once the user completes the test, you should see their result in the management pane for the test:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://speaking-test-docs.speechace.com/speechace-speaking-test/speechace-workspaces-create-manage-and-share-speaking-assessments/embedding-assessments-in-other-apps-and-websites/oembed-integration-for-speechace-speaking-test.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.