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 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 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 or creating a custom assessment. 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: [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: https://e-learning-website.com/submit_speechace_scores?courseid=91&testid=25 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=[e-mail] app_user_fullname=Jackson Sunny app_score_submission_url=https://e-learning-website.com/submit_speechace_scores?courseid=91&testid=25&userid=1234a

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.):

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 = 'https://e-learning-website.com/submit_speechace_scores?courseid=91&testid=25&userid=1234a' $app_score_submission_url = urlencode($app_score_submission_url); $app_score_submission_url = str_replace("%2F", "/", $app_score_submission_url);

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=[e-mail]&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:

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=[e-mail]&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=[e-mail]&app_user_fullname=Jackson%20Sunny &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:

{
   "version":"1.0",
   "type":"rich",
   "provider_name":"Speechace",
   "provider_url":"https://speak.speechace.co",
   "width":"100%",
   "height":"100%",
   "title":"Call center LV-426",
   "html":"<iframe width='100%' height='100%' allow='camera;microphone' src='https://speak.speechace.co/embed/ui/108?speechace_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25zdW1lcktleSI6IklsWXExendwTXJDYVVBVzMiLCJ1c2VySUQiOiIxMjM0YSIsImVtYWlsIjoiamFja0BzdW5ueS5jb20iLCJuYW1lIjoiSmFja3NvbiBTdW5ueSIsImV4cCI6MTY4MzkzNTA4NiwiaXNzIjoic3BlZWNoYWNlIiwiY291cnNlSWQiOjEwOCwicXVpeklkIjpudWxsLCJzY29yZV9zdWJtaXNzaW9uX3VybCI6IjkzOGE2M2FjYTg3N2E1YjM3N2QxNzc5ODNlYzRmZjM3NzA0NzQ5ZWJlODZhMDY3YWQ1MTNhZWI5MGU5ZmQ0M2I3ODVkZDY4YTE4NThjYmJlY2ZkMWY3NDBiYWNhNDhhY2JkM2RhYzQ0NjAyMzc3OTA1MDg3MzE3YTRlNjgyYjJjMWY0MzI5OGExZTZiNzg1OWZhYmJkN2NjIn0.oDhZniieWDX1GlhFYSSXzqepdIjH7WWfEzwU_dfnANI'></iframe>"
}

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:

Note that it is imperative to add the viewport meta tag to your HTML file header for proper viewing on mobile:

<meta name="viewport" content="width=device-width, initial-scale=1" />

<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body style="margin: 0; overflow: hidden">
    <iframe width='100%' height='100%' allow='camera;microphone' src='https://speak.speechace.co/embed/ui/108?speechace_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjb25zdW1lcktleSI6IklsWXExendwTXJDYVVBVzMiLCJ1c2VySUQiOiIxMjM0YSIsImVtYWlsIjoiamFja0BzdW5ueS5jb20iLCJuYW1lIjoiSmFja3NvbiBTdW5ueSIsImV4cCI6MTY4MzkzNTA4NiwiaXNzIjoic3BlZWNoYWNlIiwiY291cnNlSWQiOjEwOCwicXVpeklkIjpudWxsLCJzY29yZV9zdWJtaXNzaW9uX3VybCI6IjkzOGE2M2FjYTg3N2E1YjM3N2QxNzc5ODNlYzRmZjM3NzA0NzQ5ZWJlODZhMDY3YWQ1MTNhZWI5MGU5ZmQ0M2I3ODVkZDY4YTE4NThjYmJlY2ZkMWY3NDBiYWNhNDhhY2JkM2RhYzQ0NjAyMzc3OTA1MDg3MzE3YTRlNjgyYjJjMWY0MzI5OGExZTZiNzg1OWZhYmJkN2NjIn0.oDhZniieWDX1GlhFYSSXzqepdIjH7WWfEzwU_dfnANI'>
    </iframe>
  </body>
</html>

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: