> For the complete documentation index, see [llms.txt](https://docs.snapodds.com/clipshare-sdk-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapodds.com/clipshare-sdk-docs/web-sdk/javascript/sharing-clips.md). # Sharing Clips ## Description The following section deals primarily with the code used to share a clip. Share clip processes consist of two steps/screens: * First step of this process is to "snap" an image of a live TV stream and detect what is shown on it. ClipShare SDK support two "snap" targets: * Sport event: resolves a live sport event for the detected TV channel and time if any. * TV event: resolves a TV event (program, TV show, TV series, sport event and so on) shown on the detected TV channel at the given time. * Second step after TV channel and sport event (or EPG unit) were detected is to edit and share clip itself. Transitions between these steps/screens is managed by SDK itself, so it is only required to handle callback after clip was created. SDK returns a set of links with created clip (see [#result-format](#result-format "mention") for more details) that can be used: * Player: this is a link to the page hosted by Snapscreen which contains created clip. User can watch created clip here and share it. * Thumbnail: this is a link to the clip thumbnail resource. * Video: this is a link to the clip video resource. Clip video is provided in the [Apple HLS](https://developer.apple.com/streaming/) format. It can be used to create your own page where clip is shown. ## Integration With this configuration, the web component is able to "snap" an image of a live TV stream, present a clip trimming screen to the user and create a clip. It is expected that the customer's web application will use the response from the SDK to render created clip or redirect user to the provided clip player page. First, ensure both the JavaScript and CSS resource are correctly loaded and that the access token manager is correctly implemented. To render the SnapOdds SDK component, a DOM element must be provided, to which component it will be attached to as a child. In most cases, the `document.body` component works best, as the SDK is then added as the last child, which helps with styling as the SDK overlays the full view port. Next, it is necessary to configure the SDK and add it as a child to the DOM element of your choice. This can be done by using `SnapoddsSdk.clipShareBuilder()`. ## Show SDK immediately The following configuration is the simplest one and will show the SDK immediately after `appendTo()` is called. ```javascript SnapoddsSdk.clipShareBuilder() .setLanguage('en') .setAutoSnap(true) .setVibrate(true) .setAccessTokenProvider(fetchAccessTokenFromApi) .onClipCreated((clip) => /* Handle created clip here */ ) .onClose(() => console.log('SDK:onClose')) .appendTo(document.body); ``` ## Show SDK only if sportEvents are live The SDK can provide you with the information if there is at least one sports event live, based on your channel's configuration. Instead of appending the SDK to the `document.body`, you need to configure the `onLiveEventsStatusChangedCallback()` first. Therefore, you have to call `build()` instead of `appendTo()` at the end of the SDK's initialization in order for it to work. The callback you provide will be executed after initialization and will return either `true` or `false,` indicating that there is at least one live sports event available or not. After that, it will automatically check every 5 minutes for upcoming sport events. If one is found the callback will be invoked as soon as the sports event starts. ```javascript // Step1: Setup the SDK and set the onLiveEventsStatusChangedCallback() const sdk = SnapoddsSdk.clipShareBuilder() .setLanguage('en') .setAutoSnap(true) .setVibrate(true) .setAccessTokenProvider(fetchAccessTokenFromApi) .onClipCreated((clip) => /* Handle created clip here */ ) .onClose(() => console.log('SDK:onClose')) .onLiveEventsStatusChangedCallback(() => /* Toggle visibility of the UX element */) .build(); // Step2: Only when the customer interacts (e.g. clicks) on the UX element append it. sdk.appendTo(document.body); ``` ## SDK Configuration Options The following parameters are used in the `SnapoddsSdk.clipShareBuilder()`: | Method | Parameter | Default Value | Description | | --------------------------------- | ------------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | setLanguage | string | en | Set the language of the SDK. | | setAutoSnap | boolean | false | Turns on the auto snap functionality. | | setVibrate | boolean | false | Uses the phones vibrate functionality, when the snap was successful. | | setSnapTarget | 'sport' or 'epg' | sport | The target of the snap operation: sport event or TV event. | | setAction | 'create' or 'share' | 'create' | The action that should be done with clip: it should be only created or shared. | | setAccessTokenProvider | function | function that throws an error if not set | A function that takes no parameters and returns the Promise of the access token. [Access Token Handling](/clipshare-sdk-docs/web-sdk/javascript/access-token-handling.md#fetch-accesstoken-example) | | setApiUrl | string | | Switches the URL to the API server to send requests to. | | setClipShareApiUrl | string | | Switches the URL to the ClipShare API server to send requests to. | | onLiveEventsStatusChangedCallback | function(`isLive`): void | no operation | Callback function executed after initialization and when an upcoming sportsEvent becomes live | | onClipCreated | function(clip): void | no operation | Callback function executed when clip is created. [#result-format](#result-format "mention") | | onClose | function(): void | no operation | Callback function to handle SDK close events. | | appendTo | DOM Element | none | This call will finish the web component configuration and appends it to the given DOM element as child node. | | build | none | none | Returns an intermediate instance of the SdkBuilder. Needs to be used in combination with `appendTo()` later on | ## Result format `clip` has the following format: ```json { id: string, tvChannelId: number (long), timestampRefFrom: number (long), timestampRefTo: number (long), timestampRefThumb: number (long), _links: { self: { href: string (url) }, thumbnail: { href: string (url) }, video: { href: string (url) }, player: { href: string (url) } } } ```