@danim/dnm-sdk

SDK for Video Creation IFrame Integration

Overview

The dnmLoad function is designed to dynamically embed a video iframe from Danim into a specified HTML container, enabling users to integrate Danim's video functionality into their web applications seamlessly.

Installation

Include the SDK in your project:

// Using npm
npm install @danim/dnm-sdk

// Or, using Yarn
yarn add @danim/dnm-sdk

Function Parameters

The dnmLoad function accepts a single argument of type DnmLoadParams, which is an object containing the following properties:

• domId: string - The ID of the DOM element where the iframe will be inserted.
• templateShortId: string - A short identifier for the Danim template to be used.
• videoShortId: string (optional) - A short identifier for the video to be loaded.
• accessToken: string - Authentication token for API access.
• generationTimeout: number (optional) - The number of seconds to wait before timing out the video generation process. Default is 300 secondes.
• waitingText: string (optional) - Text to display while the iframe is loading. Default is a three dots loader.
  • The format of the text is HTML, you need to put \n to make a line break.
  • You can use all emojis from react-emojis. For exemple :
    • waitingText: 'Votre vidéo est en cours de création... :hourglass-done:
    • waitingText: 'Votre vidéo est en cours de création ⌛\nMerci de patienter'
• backendCallbackUrl: string (optional) - URL to which Danim will send callbacks after certain events.
• enableTestMode: boolean (optional) - If true, the function will use the test environment of Danim. Default is false.
• haltOnGenerationStart: boolean (optional) - If true, the iframe will stop when the video generation process starts. Default is true.
• logoUrl (optional) - URL of the logo to generate variables user. Default is null.
• mainColor (optional) - Main color to generate variables user. Default is null.
• secondaryColor (optional) - Secondary color to generate variables user. Default is null.
• extraColor (optional) - Extra color to generate variables user. Default is null.
• onIframeLoadCallback: () => void (optional) - A callback function that executes once the iframe has loaded.
• iframeWidth: string (optional) - Custom width for the iframe. Default is "100%".
• iframeHeight: string (optional) - Custom height for the iframe. Default is "900px".
• showGenerateButton: boolean (optional) - If true, the iframe will display a button to start the video generation process. Default is true.
• showSaveButton: boolean (optional) - If true, the iframe will display a button to save the video. Default is true.
• showMediaLibraryButton: boolean (optional) - If true, the iframe will display a button to open the media library. Default is true.
• showDeleteDraftButton: boolean (optional) - If true, the iframe will display a button to delete the draft. Default is true.

Usage

To use the dnmLoad function, you need to have a container element in your HTML with a unique ID. Pass this ID along with other required parameters to the function. For example:

dnmLoad({
  domId: 'myIframeContainer',
  templateShortId: 'xYz123',
  videoShortId: 'aBc456',
  accessToken: 'yourTokenHere',
  generationTimeout: 100,
  backendCallbackUrl: 'https://yourcallback.url',
  enableTestMode: false,
  haltOnGenerationStart: true,
  logoUrl: 'https://yourlogo.url',
  mainColor: '#ff0000',
  secondaryColor: '#00ff00',
  extraColor: '#0000ff',
  onIframeLoadCallback: function() { console.log('Iframe loaded!'); },
  iframeWidth: '80%',
  iframeHeight: '500px',
  showGenerateButton: true,
  showSaveButton: true,
  showMediaLibraryButton: true,
  showDeleteDraftButton: true
});

Handling Events

The iframe will communicate with the parent window using window.parent.postMessage. Listen to these messages to handle events:

Video Generation Started:

window.addEventListener("message", (event) => {
  if (event.data.onVideoGenerationStarted) {
    // Handle successful launch generation
    const videoId = event.data.videoId;
    const videoShortId = event.data.videoShortId;
    // Your code here
  }
});

Video Generation Completed:

window.addEventListener("message", (event) => {
  if (event.data.onVideoGenerationCompleted) {
    // Handle successful video generation
    const videoId = event.data.videoId;
    const rawUrl = event.data.rawUrl;
    const playerUrl = event.data.playerUrl;
    // Your code here
  }
});

Video Generation Timeout:

window.addEventListener("message", (event) => {
  if (event.data.onVideoGenerationTimeout) {
    // Handle timeout video generation
    // Your code here
  }
});

Video Generation Error:

window.addEventListener("message", (event) => {
  if (event.data.onVideoGenerationError) {
    // Handle video generation error
    // Your code here
  }
});

Video Saved:

window.addEventListener("message", (event) => {
  if (event.data.onVideoSaved) {
    // Handle successful launch generation
    const videoId = event.data.videoId;
    const videoShortId = event.data.videoShortId;
    // Your code here
  }
});

Error Handling

The SDK throws an error if the iframe container is not found. Ensure that the domId provided matches an existing element in the DOM.

try {
  dnmLoad({
    domId: 'myIframeContainer',
    templateShortId: 'xYz123',
    accessToken: 'yourTokenHere',
    generationTimeout: 100,
    backendCallbackUrl: 'https://yourcallback.url',
    enableTestMode: false,
    haltOnGenerationStart: true,
    logoUrl: 'https://yourlogo.url',
    mainColor: '#ff0000',
    secondaryColor: '#00ff00',
    extraColor: '#0000ff',
    onIframeLoadCallback: function() { console.log('Iframe loaded!'); },
    iframeWidth: '80%',
    iframeHeight: '500px',
    showGenerateButton: true,
    showSaveButton: true,
    showMediaLibraryButton: true,
    showDeleteDraftButton: true
  });
} catch (error) {
  console.error(error);
}

Security Tokens

Security tokens are managed by the back-end client, which has the secret key to the API application assigned to the company by the Danim back-end, on the model of Stripe client_secrets, for example (these are transmitted from the client back-end to the client front-end, in order to grant sufficient rights to continue payment operations - e.g. validation of payment intent, 3DS, ...). At Danim, the token is obtained earlier, as the display of the initial form is itself protected. Our thoughts, which are not exhaustive, are summarized according to general guidelines (who manages obtaining the token, storing the private key, etc.).

POST /tokens/generate
Content-Type: application/json

Request

For users :

{
	email: ...
	password: ...
}

For API apps :

{
	appId: ...
	appSecret: ...
}

Response

{
	success:bool
	data:object { // If success is TRUE
		token:string
		token_expires:object {
			in:int // Interval, in seconds
			at:object {
				ts: // Timestamp, in seconds
				atom: // String, format: ATOM
			}
		}
		refresh_token:string
		refresh_token_expires:object {
			in:int // Interval, in seconds
			at:object {
				ts: // Timestamp, in seconds
				atom: // String, format: ATOM
			}
		}
		xsrf:string // For cookies
	}
	message:string // If success is FALSE
	meta:object {
		warnings:string[] // Array of warnings. This is important: that will let you know if we deprecate some stuff. Please log these values.
		type:string // If success if FALSE, that will be more reliable than the message, if you want to translate the error, catch the error, etc.
	}
}