Integrate your app

TL;DR — Your server syncs Wandura's catalog every 15–60 minutes into your own database. When a viewer presses play, your app checks its own paywall, your server asks Wandura for a ticket for that one episode (plus up to two prefetches for the next episodes), and the licensed Player SDK plays it. You never hold Wandura's video keys: every ticket is checked against your licence and recorded by Wandura. Go-live = the checklist in Phase 6. Other model? See Choose an integration model. Checklist and licence price: Before you start.

This guide takes your team from a signed agreement to a live app that streams Wandura films. It follows the order a real integration runs in: what Wandura sets up for you, keys, a catalog sync job in your backend, the playback flow, the optional ad creatives feed, a test plan and a go-live checklist. Each phase links to the reference pages for the detail.

The model is simple. Your app decides whether a viewer may watch an episode (free episodes, coins, subscriptions, VIP). Wandura decides whether your app may stream the film (your licence), signs a short-lived ticket and records the play. Your app never holds the keys to Wandura's video store: your server asks Wandura for a ticket each time.

Who does what#

Phase 0: What Wandura sets up for you#

Before your developers write any code, Wandura sets up the items below. Ask for each one by name in your team's Wandura Discord channel; the order of the steps is in Get onboarded.

How roles work on the portal is explained in Roles.

Licence dates are whole days in UTC, and both the first and the last day are included. A licence without a start date applies from the moment it is granted; one without an end date runs until Wandura ends it. Wandura can also switch a licence off before its end date. You do not need to track dates yourself: the catalog lists only the films whose licence is active today.

Done when: your developers can sign in to partner.wandura.ai and open Developers, you have received the Player SDK licence, and Wandura has confirmed the list of licensed films. Your developers create the playback key themselves in Phase 1.

Phase 1: Keys and environments#

Every call goes to one base URL, https://www.wandura.ai, and only from your servers. The endpoints send no CORS headers, and a key shipped inside an app can be extracted. Authentication shows how to send a key.

Use one key per system and per environment, with only the scopes that system needs:

Rules that save you an incident later:

• Store keys in a secrets manager and read them as environment variables. Never commit them, and never put them in an app.
• Give staging and production different keys, so you can revoke one without touching the other.
• If a playback key leaks, anyone can stream your licensed films. Any Admin or Developer of your organisation can rotate or revoke it on the Developers page: revoke it immediately if you think it has leaked. To switch without downtime, create a second playback key, deploy it, then revoke the old one. Wandura is alerted whenever a new playback key is created or rotated.
• Never log a full key or a play_auth_token. When you talk to Wandura, quote the key prefix shown on the Developers page.

Creating, rotating and revoking keys step by step: Developer keys.

Test and production#

There is no sandbox. Staging and production call the same base URL, https://www.wandura.ai, and get the same answers; what keeps test traffic apart is the organisation and the key.

• Test organisation. Wandura decides whether you test in a separate test organisation. It works like any other organisation: its own members, keys and film licences.
• Test films. The films you test with are licensed to the organisation you test in. Ask for them in your team's Wandura Discord channel.
• Test plays. Every ticket request is recorded, test ones included. Put a prefix such as qa- in viewer_ref for test traffic, and tell Wandura which organisation is your test one.

Done when: each backend system has its own key in your secrets manager, and a GET /api/delivery/v1/catalog call from your staging server returns 200.

Phase 2: Catalog sync job#

Build a job in your backend that copies the Wandura catalog into your own database. Your app reads films from your database: never from Wandura directly, and never from a second film list that someone maintains by hand.

How often#

Run the job every 15 to 60 minutes, and let someone trigger it by hand when Wandura tells you about a new release. The catalog sends no change notifications, so polling is how you see changes. Do not call the catalog on app launch: serve it from your server.

No cursor, no pagination#

Each response is the complete catalog your organisation may stream at that moment. There is no cursor, page or updated_since parameter. Treat every response as a snapshot and compare it with your copy.

What to store#

Every field is described in the catalog reference. The points that matter for a sync job:

• Order. Films arrive sorted by display_order. Keep that order; Wandura edits it.
• Free episodes. Episodes with episode_no up to and including free_until_episode are free. Read it on every sync, because it can change.
• Coming soon. Rows with "id": null and "status": "planned" stand for episodes that are not published yet. Show them as "coming soon" and never send them to playback.
• Readiness. Grey out or hide episodes with "stream_ready": false.
• Artwork and text. poster_url and synopsis_full can be null: show a placeholder image, or nothing. The episode poster_uri is not guaranteed to be a loadable URL, so fall back to the film poster.
• Subtitles are not in the catalog. They come with each playback ticket; see Phase 3.

Your own publish gate#

You decide when a film appears in your app. A simple rule that avoids empty or broken tiles: show a film only when it has a title, a poster and at least its first episode with "stream_ready": true. Keep films that fail the rule in your database and check them again on the next sync.

Withdrawn films and episodes#

A film leaves the catalog when your licence for it ends or is switched off, or when the film is withdrawn. An episode leaves the catalog when it is withdrawn. Nothing announces it: the row is simply missing from the next response.

When a row is missing:

1. Mark it unavailable in your database, and stop showing and selling it. Do not delete it: your viewers' purchases and watch history still point at it.
2. If it comes back in a later response, for example after a licence renewal, mark it available again.
3. If the call fails (any status other than 200), keep your previous copy and try again on the next run. Never treat a failed call as an empty catalog.

A stale copy cannot let anyone watch a withdrawn film: every ticket request checks your licence again, and the ticket answer is the one that counts.

Done when: your staging app shows the licensed films in Wandura's order, from your own database, with free episodes, "coming soon" tiles and greyed-out episodes shown correctly.

Phase 3: Playback flow#

When a viewer taps an episode, your backend first applies your own paywall. Only if the viewer may watch does it ask Wandura for a ticket.

1. Check your paywall first#

Wandura checks only that your organisation may stream the film. It does not know your viewers, so it issues a ticket for any episode of a licensed film. Keeping locked episodes locked is your backend's job: never request a ticket for an episode the viewer has not unlocked.

2. Request the ticket from your server#

Your backend calls POST /api/delivery/v1/playback with the playback key and sends the episode (episode_id, or film_ref and episode_no), the two device values from the Player SDK (union_info and drm_kek), your own viewer_ref and "intent": "play". The full request and response are in the playback reference and on Playback.

• Send the device values exactly as the Player SDK produced them. If an SDK call returns nothing, fix the app rather than sending a placeholder string. See sending the device values.
• Set viewer_ref to an opaque ID of your own, such as <user-id>:<device-id>. Never put an email address or a name in it.
• Before returning the answer to the app, check that protection is private-encrypted. If it is anything else, do not play or sell the episode, and contact Wandura.

3. Play on the device#

The app passes vid and play_auth_token to the Player SDK and starts playback. The SDK fetches the encrypted stream and its keys by itself. A standard video player cannot play these episodes: it loads the playlist and then stalls. Follow every setup step in the Player SDK guide on the portal (Developers → Player SDK); a missed step often shows up only as a player that never starts.

4. Prefetch the next two episodes#

Short dramas are watched back to back, so the next episode should start at once. Right after the current episode starts, your backend requests tickets for up to the next two episodes, with "intent": "prefetch", so the app can load them ahead of time.

• Each request covers one episode, so this means up to two extra requests. There is no batch request.
• Apply your paywall to each of them. Do not prefetch an episode the viewer has not unlocked.
• Skip placeholder rows and episodes with "stream_ready": false.
• A prefetch is not counted as a play. When the viewer actually moves on to the next episode, that is a new play start: request its ticket with "intent": "play", and prefetch the two after it.
• Every request, prefetches included, counts toward your organisation's rate limit. Never request tickets for a whole film.

5. Expiry and retry#

A ticket is valid for 30 minutes; expires_at gives the exact time. Do not keep tickets between play starts. When the Player SDK reports an error during playback, including an expired ticket:

1. Request one fresh ticket and reload the player at the current position.
2. If that request fails, map its error_code to what the viewer sees, using the table below. Retry once, not in a loop.

A prefetched ticket that expired before the viewer reached the episode is simply replaced by a new request.

6. Subtitles#

Each ticket response lists the episode's subtitles as WebVTT files, one per language. An empty list means none are attached yet; it is not an error. Subtitle URLs outlive the ticket, so you can cache them per episode; when Wandura replaces a subtitle, its URL changes, so refresh the list from the next ticket. In a web player, download the file with fetch and add the cues yourself, instead of a <track> element with crossorigin. See Subtitles.

What the viewer sees for each answer#

Branch on error_code, keep a default branch for codes you do not know, and never show Wandura's error text to viewers.

Every code, with its exact body, is listed in Errors.

Done when: on a real iPhone and a real Android phone, a free episode plays with subtitles, a locked episode shows your paywall without any call to Wandura, and the next episode starts without a wait.

Phase 4: Ad creatives feed (optional)#

Skip this phase unless your organisation builds ad creatives from Wandura films on partner.wandura.ai. If it does, your marketing systems can sync a record of each approved creative.

1. Create a key with the creatives:export scope on the Developers page.
2. Sync incrementally: page through GET /api/delivery/v1/creatives with cursor, keep the largest updated_at as a checkpoint, and pass it as updated_since on the next run.
3. Store records keyed by creative_id, and overwrite them when they arrive again.
4. rights.ends_at is 00:00 UTC of the last day of your export rights, and that day is included: stop using a creative after that UTC day ends, at rights.ends_at + 86400. To check a stored creative, call GET /api/delivery/v1/creatives/{id}: 404 with code 4040 means it is no longer available.

Records describe each creative and never include a media URL. Ask Wandura how final video files reach your systems. Details: Creatives.

Phase 5: Test plan#

A QA engineer can run this list on a staging build against your staging backend, in the organisation you test in (see Test and production). Use real phones for playback. There is no sandbox, and every ticket request is recorded, test ones included: put a recognisable prefix such as qa- in viewer_ref for test traffic, and tell Wandura which organisation is your test one.

Keys and security

• Search the built iOS and Android apps for wnd_live_. There must be no match.
• Backend logs contain no full API key and no play_auth_token.
• A catalog call without a key returns 401, and one with a key that lacks metadata:read returns 403. Your job raises an alert and keeps its previous copy.

Catalog

• The films in the app match the licence list confirmed by Wandura.
• Films appear in the same order as in the API response.
• Episodes up to free_until_episode open without payment; the next one shows your paywall.
• Placeholder episodes show "coming soon" and cannot be tapped.
• Episodes with "stream_ready": false are greyed out or hidden.
• A film without a poster shows your placeholder image, not an empty box.
• When one sync run fails (for example, with the network blocked for the job), the catalog in the app stays unchanged.

Playback

• A free episode plays on a real iPhone and a real Android phone.
• Subtitles appear, and switching language works. An episode without subtitles plays without an error.
• A locked episode shows your paywall, and your backend logs show no ticket request for it.
• After unlocking, the same episode plays.
• While an episode plays, the backend requests the next two episodes with "intent": "prefetch", and skips any the viewer has not unlocked.
• Moving on to the next episode starts it quickly and sends a new "intent": "play" request.
• Pausing for more than 30 minutes and then resuming leads to one fresh ticket and playback from the same position.
• Switching the phone to airplane mode mid-episode and back again recovers without a crash.
• A backend test that sends "(null)" as a device value receives 400 invalid_device_info and raises an alert.

Rights ending

• Ask in your team's Wandura Discord channel to end the licence of one test film in the organisation you test in. After the next sync the film is hidden, and a ticket request for it returns 403 not_entitled, which the app shows as "no longer available".
• Viewers who had paid for that film see the message agreed with your support team.

Phase 6: Go-live#

Checklist#

• Production keys are issued and stored, separate from staging keys.
• The Player SDK licence covers the bundle ID and package name of the production apps.
• Wandura has confirmed the licensed films and their licence windows.
• The catalog sync job runs on schedule in production, with an alert on failure.
• The paywall reads free_until_episode from your synced catalog.
• The backend checks protection on every ticket.
• Every answer in the Phase 3 table maps to a screen, and unknown codes fall into a default branch.
• Your on-call runbook names who revokes the playback key if it leaks (any Admin or Developer of your organisation) and who tells Wandura.
• The whole test plan passed on the release build.

What to monitor#

When rights end#

• Licence end date. The last day of the window is included (UTC). From the next day the film is missing from the catalog, and ticket requests for it return 403 not_entitled.
• Licence switched off early, or organisation suspended. New ticket requests are refused right away. A suspended organisation also gets 403 from the catalog.
• Sessions already playing. Tickets already issued are never extended. Design the app so that playback can end with a player error at any time, and follow the retry steps in Phase 3.
• Your side. Stop selling the film, apply your refund policy, and stop using its creatives once the UTC day of rights.ends_at has ended.
• Renewal. A renewed film comes back in the next sync; mark it available again.

Who to contact#

Related#

• Quickstart: your first calls in a few minutes.
• Catalog and Playback: how each part works.
• Errors and Rate limits.
• FAQ.