Developer Site

Widget Interfaces to Get Media from your Users

This document describes how to integrate SendUs widgets into your website or application to get media from your users.

The default widgets come fully loaded to deliver the entire submission process, including the metadata step for the user to title, describe, tag and agree to the media rights agreement.

The widgets can also be configured to your needs. For example, if you prefer to get more information from users you can add custom input fields to the metadata form. If you prefer to present your users with your own metadata step and add your own options/fields then you can turn off the widget metadata step.

The widget will make Javascript callbacks to let you know what stage in the process the widget is in and deliver any important data to your scripts.

The SendUs widgets also include content creation tools, like the webcam, photo editor and video editor tools. This enables your users to CREATE content and then submit it!

The SendUs Widgets available

There are six types of widgets that enable you to get content from your users:

Video and Photo Submission Widget   See Example

Select submission method(s)  Web Mobile

  • Upload - video and photos (configured ON or OFF)
  • Facebook Album – photos and videos (configured ON or OFF)
  • Google Accounts – photos (configured ON or OFF)
  • YouTube Accounts – videos (configured ON or OFF)
  • Webcam record – record videos (configured ON or OFF)
  • Go Mobile! – instruction to submit via the SendUs mobile app (configured ON or OFF)

Selected submission method action  Web Mobile

Metadata steps (configured ON or OFF)

Thank you screen (configured ON or OFF)  Web Mobile

Upload Only Submission Widget   See Example

Upload button  Web Mobile

Metadata steps (configured ON or OFF)

Thank you screen (configured ON or OFF)  Web Mobile

Webcam Record and Submission Widget   See Example

Webcam recorder  Web

Metadata steps (configured ON or OFF)
  • Title, Describe, Tag (STEP)  Web

  • User Info (STEP)  Web

    Thank you screen (configured ON or OFF)  Web

  • Photo Editor and Submission Widget   See Example

    Splash screen with list of saved edits to re-open (configured ON or OFF)

    Photo editor  Web

    Metadata steps (configured ON or OFF)

    • Title, Describe, Tag (STEP)  Web
    • User Info (STEP)  Web

    Thank you screen (configured ON or OFF)  Web

    Video Editor and Submission Widget   See Example

    Splash screen with list of saved edits to re-open (configured ON or OFF)

    Video editor  Web

    Metadata steps (configured ON or OFF)

    • Title, Describe, Tag (STEP)  Web
    • User Info (STEP)  Web

    Thank you screen (configured ON or OFF)  Web

    Watch and Submit Widget   See Example

    View previously submitted media  Web

    Select submission method(s)  Web

    • Upload - video and photos (configured ON or OFF)
    • Facebook Album – photos and videos (configured ON or OFF)
    • Google Accounts – photos (configured ON or OFF)
    • YouTube Accounts – videos (configured ON or OFF)
    • Webcam record – record videos (configured ON or OFF)
    • Go Mobile! – instruction to submit via the SendUs mobile app (configured ON or OFF)

    Selected submission method action  Web

    Metadata steps (configured ON or OFF)

    • Title, Describe, Tag (STEP)  Web
    • User Info (STEP)  Web

    Thank you screen (configured ON or OFF)  Web

    Embedding a Widget

    The embed code is exactly the same for all widgets. The account_id and device_id attributes in the cg_widget_container div determine which widget to load in.

                <script src="http://apps.sendus.com/embed/cg.v2.js" type="text/javascript"></script>
    <div class="cg_widget_container" account_id="58" device_id="370"></div>
    • class = cg_widget_container required
    • account_id = unique ID of your account (example: 58) required
    • device_id = device you want to load required

    The widgets will automatically take the width of whatever container it is embedded in. So if you put the widget in a 500px DIV, then the widget will load and take up the 500px width space.

    NOTE: The photo and video editors require a minimum of 760px.

    Advanced embed options

    The embed code contains additional attributes for div class cg_widget_container which allow you to input additional data into the iframe.

    Custom Tags:

    Custom tags which will be automatically added to the media submission. For example, a custom tag could be a product ID on your system or a user ID of the person on your system. Later, you’ll be able to request media by these custom tags to display to the user.

    Attribute:

    su_custom_tags='{"abc":"xyz"}'

    su_custom_tags='{"abc":"xyz", “123”: {"456":"789"}}'

    Note: the first example shows one simple parameter. The second example shows how you can create nested tags.

    Filter Media Tags:

    Note: This is only used if you are using a submission widget that ALSO is displaying a list of media, like the "Watch and Submit Widget".

    Filter media tags will automatically filter the media displayed in the widget. For example, if you were using a product ID "Custom Tag" then you could also put that product ID in the "Filter Media Tag" so that the media displayed were only for that product. This allows you to load a widget on the page and attach it to any object you want. Both submissions and the media displayed will correlate to that object.

    Attribute:

    su_medialist_filter_tags ="{"abc":"xyz"}"

    su_medialist_filter_tags ="{"abc":"xyz", “123”: {"456":"789"}}"

    Note: the first example shows one simple parameter. The second example shows how you can filter by nested tags.

    Protocol – HTTP or HTTPS

    This will load in all HTTP or HTTPS content inside the iframe. Default is HTTP.

    Attribute:

    protocol="https"

    User ID:

    If you are creating and connecting users on the SendUs platform and you know the SendUs user ID then you can drop it in here. Users are not created on the SendUs platform by default. This is something you have to enable if you want to do this. Contact us at support@sendus.com for more info.

    Attribute:

    user_id="4556"

    User Token:

    If you are creating and connecting users on the SendUs platform and you know the SendUs user TOKEN then you can drop it in here. Users are not created on the SendUs platform by default. This is something you have to enable if you want to do this. You would use this if you were using the video editor and wanted to enable users to save and later re-open a saved edit. Contact us at support@sendus.com for more info.

    Attribute:

    user_token="a798sdaf7dd98f7ds"

    Example of advanced embed options:

                    <script src="http://apps.sendus.com/embed/cg.v2.js" type="text/javascript"></script>
    <div class="cg_widget_container" account_id="58" device_id="370" su_custom_tags='{"abc":"xyz"}'></div>

    Multiple widgets on a page:

    In some cases you may want to have multiple widgets in the same page. You may want to create your own submit process and open many submit widgets within the same page separately.

    To have multiple widgets on a page, you must:

    1. Add another div with class cg_widget_container for each additional widget you want to add. Each div needs to have the unique device_id of the widget.
    2. You include the cg.v2.js file only once!

    Example:

                    <script src="http://apps.sendus.com/embed/cg.v2.js" type="text/javascript"></script>
    <div class="cg_widget_container" account_id="58" device_id="370"></div>
    <div class="cg_widget_container" account_id="58" device_id="371"></div>

    Remove the "Thank You" Step

    You can turn off the final step of the default widgets, which thanks the user for submitting and provides a button that let’s the user return to the first step to submit again.

    The reason you might want to turn this step off if you want to present the user with your own “thank you” screen or if you wanted to automatically take the user to a different screen when they were done. Instead of taking the user to the “thank you” step in the widget, a Javascript callback will trigger letting the parent page know that the user is “done” submitting a media. Information about the media is included in this callback.

    To do this:

    • Turn off the “Confirmation” screen from your widget manager
    • Leverage the Javascript callback callbackAfterSubmit() that is triggered. It is described here. When you receive this callback you can take the user to another page or part of the experience.
    See Example

    Re-load a widget on a page

    If you want to reload the entire widget into the interface without refreshing the page, please use this function:

                

    $(".cg_widget_container").empty();

    var widgets = [];

    $('.cg_widget_container').each(function(index){

    widgets[index] = new Widget(this,index);

    widgets[index].show_widget();

    });

    Add custom input fields on the metadata step

    From your widget manager, click on “Advanced” to reveal the ability to add custom input fields. You can select from different input field types and mark if they are mandatory fields. If mandatory, you can insert your own alert message.

    These additional fields are displayed on the second metadata step during the submission process.


    Custom Input Fields

    See Example

    Turn OFF the metadata step

    Reasons why you might not want to display this form to your users:

    • If you do not want to use the SendUs metadata form for collecting information about the media submission, you can turn this step off so that you can instead build your own form and then run an API call to submit the media.
    • If you don’t want to present the user with a form at all and instead input your own metadata, you can insert this data into an API call to submit the media.

    Note: When you turn OFF the metadata step it will also turn off the confirmation step, which follows it.

    Instead of going to the metadata step the widget will trigger a Javascript callback with information about the media submission in progress. Depending on the method the user chooses, the response and workflow to follow is slightly different. If the user uploaded a video, for example, then the callback would contain that upload’s new media ID on SendUs. If the user recorded a video using the webcam tool then the callback would return the public URL to the resulting video.

    It is then up to your code to take that data and run an API call which inserts that media as a submission to your SendUs account.

    To do this:

    • Turn off the "Metadata" step from your widget manager
    • Leverage the Javascript callback callbackAfterComplete () that is triggered. It is described here.

    Here are the different methods:

    Upload

    • JS Callback = media ID on SendUs
    • API call to make = Submit Insert - by Media ID

    Webcam

    • JS Callback = public URL to temporary video file
    • API call to make = Submit Insert - by External File

    Facebook Media

    • JS Callback = public URL to file on Facebook servers
    • API call to make = Submit Insert - by External File

    Google Media

    • JS Callback = public URL to file on Google servers
    • API call to make = Submit Insert - by External File

    YouTube Video

    • JS Callback = YouTube video ID
    • API call to make = Submit Insert - by YouTube Video ID

    Photo Editor

    • JS Callback = edit ID on SendUs
    • API call to make = Submit Insert - by Edit ID

    Video Editor

    • JS Callback = edit ID on SendUs
    • API call to make = Submit Insert - by Edit ID

    Example

    Pure Source energy drink used the webcam tool to capture video testimonials from their users (customers). The user would record their video using the webcam tool in the widget. After finishing with the webcam tool, the widget would automatically run a JS callback to a script in the Pure Source page. The code on that page then presented the user with a custom form to fill in the title, description, tags and other information. When the user was done and clicked save, the Pure Source code would then run the “Submit Insert - by External File” API call while including some of the information input into the form by the user. The API call returns “success” and the Pure Source code takes the user to a custom confirmation page.

    1. Load webcam widget
    2. User records a video and clicks "save"
    3. JS Callback including URL to video file
    4. Pure Source code stores this as a variable
    5. Pure Source shows a form to the user
    6. User fills the form out
    7. User clicks "Finish"
    8. Pure Source code inputs the video file URL from the callback and the data from the form into the "Submit Insert - by External File" SendUs API call
    9. SendUs API call returns "Success"
    10. Pure Source code takes the user to a confirmation screen
    11. The video is now inside the Pure Source SendUs Media Manager, ready for review and moderation
    See Example

    See the Submit Insert API call

    Add your custom unique identifiers to a submitted media

    Add unique identifiers from your system to a submitted media in order to tag and track it. For example, add a user ID from your system to a submitted media so that you can track content by user. Or add a product ID from your system to link media to specific products. Later, you’ll be able to request media by these custom tags to display to the user.

    Please refer to the "Custom Tags" area in the widget embed code area.

    Enable users to save their work in the video editor

    In order for your users to save their work, they must be registered users on the SendUs platform.

    To accomplish this you must connect your users in the background by creating a SendUs account through an external connection API call. This requires that you run an API call to the SendUs platform prior to opening the widget to create/connect a user. This is called the “External Connect” API call. It will return the user token which is required for the video editor to enable the “save” feature.

    Please contact us at support@sendus.com if you’re interested in this functionality.

    Open a previously saved edit inside the video editor

    This requires that you have the user token in addition to the unique ID of the saved edit.

    Please contact us at support@sendus.com if you’re interested in this functionality.

    Javascript Callbacks:

    The SendUs widgets use Javascript callbacks to communicate the status of the user in the workflow and transfer important data to scripts in your web page. These callbacks become important when you have turned off steps within the widget.

    The three callbacks are:

    • callbackAfterSubmit() - used when the confirmation/thank you step is turned off
    • callbackAfterEditClose() - used when a user clicks "close" in the photo or video editor
    • callbackAfterComplete() - used when metadata step is turned off

    callbackAfterSubmit()

    This is triggered when the user is done submitting their media and the “confirmation / thank you” screen in the widget has been configured to be OFF. You can simply use this callback as a trigger to then run a script that takes the user to a custom confirmation screen.

    This Javascript callback also contains data about the media just submitted by the user. This includes the ID, hash, title, description and more. You could take the user to a page to display the media where you’d input the submit’s hash inside the SendUs media embed code. As soon as the media was approved and converted then the user could see the media.

    function callbackAfterSubmit(data){}

    This function is called after a user finishes the metadata step in the submit process when the submit confirmation step is turned off for that widget.

    In the function, you will get a variable with all the information about the media just submitted.

    data

    (you can see this information in your browser console by console.log(data))

    {"result":{"success":1,"submit":{"submit_id":9334,"submit_hash":"xo2nts","submit_type":"image","submit_status":"active","submit_project_limit":"ok","submit_is_original":1,"submit_is_public":1,"submit_is_vetted":0,"submit_is_conv":"converted_full","submit_title":"Random title 1358206280","submit_time_create":1358206280,"submit_duration":0,"submit_url":"http://core_server_dev.sendus.com/350/123#!/media/xo2nts","submit_user_id":1932,"submit_in":0,"submit_out":0,"submit_price":0,"submit_media_id":9019,"submit_edit_id":0,"submit_callout_id":1076,"submit_project_id":145,"submit_project_title":"Milind-Is-Funky","submit_frame_size":"488x263","submit_rotate":0,"submit_project_url":"http://core_server_dev.sendus.com/350/123#!/"}},"id":"request-1358206280","jsonrpc":"2.0"}

    callbackAfterEditClose()

    The photo and video editor have a “close” button in the interface. This callback will run when the user clicks “close” so that your page knows that the user wants to leave the editing interface. You can then run a script which removes the widget from the page and takes the user back to the previous step you have in your user experience.

    function callbackAfterEditClose(params){}

    This function is called when someone hits the close button on either the photo or video editor and the splash screen is configured off

    params

    {"edit_type":"video_editor"}

    {"edit_type":"image_editor"}

    callbackAfterComplete()

    This callback occurs on widgets where the metadata step is turned off.

    This Javascript callback includes information about the media that you will need to then submit it using the SendUs "Submit Insert" API call.

    function callbackAfterComplete(params){}

    This function is active when the metadata step is turned off. It is triggered after the user is done uploading, selecting or creating their media.

    In the function, you will get variables with all the information you need about the media to run the "Submit Insert" API call and to determine which parameters to use in the “submit insert” API call.

    submitssion type

    params

    Submit Insert API Call to use

    upload

    {"submit_insert_api":"media_id","data":{"media_id":50499}}

    Submit Insert – by Media ID

    facebook

    {"submit_insert_api":"external","data":{"source_type":"facebook","source_id":"397497530261547","source_url":"https://fbcdn-sphotos-e-a.akamaihd.net/hphotos-ak-ash3/s2048x2048/523066_397497530261547_1270081620_n.jpg"}}

    Submit Insert – by External File

    google

    {"submit_insert_api":"external","data":{"source_type":"google","source_id":"5798563810804526242","source_url":"http://redirector.googlevideo.com/videoplayback?id=2b3c60bc16745349&itag=35&source=picasa&cmo=sensitive_content%3Dyes&ip=0.0.0.0&ipbits=0&expire=1370627463&sparams=id,itag,source,ip,ipbits,expire&signature=76BBB4AFDB17FF3C3931C4403827903073CC6AC8.3AA90EF3939EE42794205BA58812E845F731927&key=lh1"},"source_filename":"VIDEO0032.3gp"}

    Submit Insert – by External File

    youtube

    {"submit_insert_api":"external","data":{"source_type":"youtube","source_id":"9mZ2sxCaClc"}}

    Submit Insert – by YouTube ID

    webcam

    {"submit_insert_api":"external","data":{"source_type":"webcam","media_id":50499,”source_id":"H0zf6zf7AAd0xi7FFi0z","source_url":"http://23.21.37.153:5080/oflaDemo/stream/V0zg7xh0zg4wh4wg0u.flv"}}

    Submit Insert – by Media ID

    video editor

    {"submit_insert_api":"edit_id","data":{"edit_id":14301,"edit_title":"xvcb","edit_type":"video_editor","token":""}}

    Submit Insert – by Edit

    photo editor

    {"submit_insert_api":"edit_id","data":{"edit_id":14299,"edit_type":"photo_editor","token":""}}

    Submit Insert – by Edit

    Javascript Callback Example Code:

    In this example, you’ll see the Javascript function in the parent page for "callbackAfterSubmit" which will run a simple alert displaying the submit_id of the media just submitted.  Also, in this example we show that you can display all of the submit data in your console. This will allow you, the developer, to see what data you have available to you in the callback (note: console.log will throw errors in IE and some versions of Firefox)

                <html>
    <head>
    <script src="http://apps.sendus.com/embed/cg.v2.js" type="text/javascript"></script>
    <script type=”text/javascript”>
        function callbackAfterSubmit(data){
                 //console.log(data);
                 alert(data.submit.submit_id);

    </script>
    </head>
    <body>
    <div class="cg_widget_container" account_id="account ID here" device_id="yourDeviceID"></div>
    </body>
    </html>

    • The SendUs Widgets available
    • Embedding a Widget
    • Advanced embed options
    • Remove the "Thank You" Step
    • Re-load a widget on a page
    • Add custom input fields on the metadata step
    • Turn OFF the metadata step
    • Add your custom unique identifiers to a submitted media
    • Enable users to save their work in the video editor
    • Open a previously saved edit inside the video editor
    • Javascript Callbacks
    ©2013 CitizenGlobal, Inc.
    X