Change history
Every change to this page, newest first. Expand an entry to see what changed.
- 1 Oct 2026 · +8 −8 lines
Show changes
⋯ | Developer access | Your backend developers get the **Developer** role. It opens only the **Developers** page, where keys are managed. Your organisation Admin can manage keys too. | The emails of your developers. | | Film licences | A streaming licence for each film you may show. Its window can have a start date, an end date, both or neither. | The list of films and dates in your agreement. | - | Playback key | An API key with the `playback` scope. Only Wandura issues it. | Which of your environments need one, for example staging and production. | + | Playback key | An API key with the `playback` scope. Your developers create it themselves on the **Developers** page, one per environment. If it leaks, anyone can stream your licensed films, so revoke it immediately. | Nothing: you create it yourself. | | Player SDK licence | Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. It comes with access to the Player SDK guide on partner.wandura.ai → **Developers** → **Player SDK**. | The iOS bundle ID and Android package name your app will ship with, not temporary ones. | ⋯ 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 playback key and the Player SDK licence, and Wandura has confirmed the list of licensed films. + **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). ## Phase 1: Keys and environments {#phase-1} ⋯ |---|---|---| | Catalog sync job | `metadata:read` | Your developers, on the **Developers** page | - | Playback service (the server that requests tickets) | `playback` | Wandura | + | Playback service (the server that requests tickets) | `playback` (with `metadata:read`: pick **Stream films in an app**) | Your developers, on the **Developers** page | | Marketing sync job (only if you use [Phase 4](#phase-4)) | `creatives:export` | Your developers, on the **Developers** page | ⋯ - 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. - - A playback key is rotated by Wandura, not in the portal. To switch without downtime, Wandura creates a new playback key next to the old one, you deploy it, and then Wandura revokes the old key; both keys work in between. Only your organisation **Admin** can revoke a playback key from the portal: that is your emergency switch if you think it has leaked. + - 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. ⋯ - [ ] 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 (your organisation Admin) and who tells Wandura. + - [ ] 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](#phase-5) passed on the release build. ⋯ | Need | Contact | |---|---| - | Organisation setup, playback keys and their rotation, film licences and dates, the Player SDK licence, a rights-end test | Wandura, in your team's Wandura Discord channel | + | Organisation setup, film licences and dates, the Player SDK licence, a rights-end test | Wandura, in your team's Wandura Discord channel | | The **Developer** role for a new developer | Your organisation Admin on partner.wandura.ai | - | Keys you create yourself (`metadata:read`, `creatives:export`) | Your developers, on the **Developers** page | - | A playback key that may have leaked | Your organisation Admin revokes it first, then tells Wandura | + | Every key, playback keys included: create, rotate, revoke | Your developers, on the **Developers** page | + | A playback key that may have leaked | An Admin or Developer of your organisation revokes it first, then tells Wandura | | Repeated `5xx` answers or other outages | Wandura, in your team's Wandura Discord channel, with the details listed in [Support](help/support.md) | ⋯
- 1 Oct 2026 · +25 −16 lines
Show changes
⋯ |---|---|---| | Films | Produces, encodes and protects every film and episode. Keeps titles, synopses, posters, genres, display order and subtitles up to date. | Shows them in your app, in the order and with the text you receive. | - | Rights | Grants your organisation a streaming licence per film, with a start and an end date, and checks it on every ticket request. | Follows any other limits in your contract, for example the countries where your app may show a film. | + | Rights | Grants your organisation a streaming licence per film, with a licence window (a start date, an end date, both or neither), and checks it on every ticket request. | Follows any other limits in your contract, for example the countries where your app may show a film. | | Viewers and money | Nothing. The API has no per-viewer identity. | Accounts, sign-in, paywall, free episodes, coins, subscriptions, VIP, refunds and viewer support. | | Keys | Issues the key that can play video. Lets your developers create read-only keys themselves. | Keeps every key on your servers, rotates and revokes keys, never ships a key inside an app. | - | Player | Provides the Player SDK licence and registers your app IDs. | Integrates the Player SDK in your apps and follows its onboarding pack. | + | Player | Registers your app IDs and issues the Player SDK licence; your organisation pays for it. | Integrates the Player SDK in your apps and follows the Player SDK guide on the portal. | | Playback | Signs a ticket for one episode on one device, and records the play. | Requests a ticket only for episodes the viewer may watch, and hands it to the player. | | Usage | Counts plays per film from your ticket requests. | Marks prefetch requests as prefetches, so they are not counted as plays. | ⋯ ## Phase 0: What Wandura sets up for you {#phase-0} - Before your developers write any code, Wandura sets up the items below. Ask for each one by name. + 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](before-you-start.md#get-onboarded). | Item | What it is | What you give Wandura | ⋯ | Organisation | Your team's workspace on [partner.wandura.ai](https://partner.wandura.ai). Every key and licence belongs to it. | Your organisation name and the email of the person who will be its **Admin**. | | Developer access | Your backend developers get the **Developer** role. It opens only the **Developers** page, where keys are managed. Your organisation Admin can manage keys too. | The emails of your developers. | - | Film licences | A streaming licence for each film you may show, with a start date and an end date. | The list of films and dates in your agreement. | + | Film licences | A streaming licence for each film you may show. Its window can have a start date, an end date, both or neither. | The list of films and dates in your agreement. | | Playback key | An API key with the `playback` scope. Only Wandura issues it. | Which of your environments need one, for example staging and production. | - | Player SDK licence | The licence for the Player SDK that decrypts Wandura films, tied to your app IDs. Your organisation pays for it. | The iOS bundle ID and Android package name your app will ship with, not temporary ones. | + | Player SDK licence | Wandura registers your app IDs and issues the Player SDK licence; your organisation pays for it. It comes with access to the Player SDK guide on partner.wandura.ai → **Developers** → **Player SDK**. | The iOS bundle ID and Android package name your app will ship with, not temporary ones. | How roles work on the portal is explained in [Roles](../partners/roles.md). - Licence dates are whole days in UTC, and both the first and the last day are included. 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. + 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 playback key and the Player SDK licence, and Wandura has confirmed the list of licensed films. ⋯ - 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. - - A playback key is rotated by Wandura, not in the portal. Only your organisation **Admin** can revoke it: that is your emergency switch if you think it has leaked. + - A playback key is rotated by Wandura, not in the portal. To switch without downtime, Wandura creates a new playback key next to the old one, you deploy it, and then Wandura revokes the old key; both keys work in between. Only your organisation **Admin** can revoke a playback key from the portal: that is your emergency switch if you think it has leaked. - 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](../partners/developer-keys.md). + ### Test and production {#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`. ⋯ ### 3. Play on the device {#play-on-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 your Player SDK onboarding pack; a missed step often shows up only as a player that never starts. + 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 {#prefetch} ⋯ ### 6. Subtitles {#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. In a web player, download the file with `fetch` and add the cues yourself, instead of a `<track>` element with `crossorigin`. See [Subtitles](concepts/playback.md#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](concepts/playback.md#subtitles). ### What the viewer sees for each answer {#viewer-messages} ⋯ | `400` `invalid_request` or `invalid_device_info`, `409` `sdk_required` | A bug in how your app reads the Player SDK values | "Couldn't load this episode" | Alert your engineers; do not retry | | `401`, or `403` without `error_code` | Wrong, revoked or unscoped key | "Couldn't load this episode" | Alert your engineers; check the key | + | `503` `service_unavailable` | Wandura could not verify your key in time; the key is fine | "Couldn't load this episode, try again" | Retry after `Retry-After`, with backoff; do not rotate the key | | `429` `rate_limited` | Too many requests | "Busy, try again in a moment" | Wait for `Retry-After`, then find the loop | | `502` | Temporary problem on Wandura's side | "Couldn't load this episode" | Retry with backoff, then give up | ⋯ 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. Stop using a creative once its `rights.ends_at` has passed. To check a stored creative, call `GET /api/delivery/v1/creatives/{id}`: `404` with `code` `4040` means it is no longer available. + 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](concepts/creatives.md). ⋯ ## Phase 5: Test plan {#phase-5} - A QA engineer can run this list on a staging build against your staging backend. Use real phones for playback. Every ticket request is recorded, test ones included, so put a recognisable prefix such as `qa-` in `viewer_ref` for test traffic. + 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](#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** ⋯ **Rights ending** - - [ ] Ask Wandura to end the licence of one test film. 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". + - [ ] 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. ⋯ - [ ] 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 start and end dates. + - [ ] 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. ⋯ - **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 after `rights.ends_at`. + - **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. ⋯ | Need | Contact | |---|---| - | Organisation setup, playback keys and their rotation, film licences and dates, the Player SDK licence, a rights-end test | Wandura | + | Organisation setup, playback keys and their rotation, film licences and dates, the Player SDK licence, a rights-end test | Wandura, in your team's Wandura Discord channel | | The **Developer** role for a new developer | Your organisation Admin on partner.wandura.ai | | Keys you create yourself (`metadata:read`, `creatives:export`) | Your developers, on the **Developers** page | | A playback key that may have leaked | Your organisation Admin revokes it first, then tells Wandura | - | Repeated `5xx` answers or other outages | Wandura, with the details listed in [Support](help/support.md) | + | Repeated `5xx` answers or other outages | Wandura, in your team's Wandura Discord channel, with the details listed in [Support](help/support.md) | ## Related ⋯
- 1 Oct 2026 · +12 −12 lines
Show changes
⋯ ## Phase 0: What Wandura sets up for you {#phase-0} - Before your developers write any code, your Wandura partner contact sets up the items below. Ask for each one by name. + Before your developers write any code, Wandura sets up the items below. Ask for each one by name. | Item | What it is | What you give Wandura | ⋯ | Film licences | A streaming licence for each film you may show, with a start date and an end date. | The list of films and dates in your agreement. | | Playback key | An API key with the `playback` scope. Only Wandura issues it. | Which of your environments need one, for example staging and production. | - | Player SDK licence | The licence for the Player SDK that decrypts Wandura films, tied to your app IDs. | The iOS bundle ID and Android package name your app will ship with, not temporary ones. | + | Player SDK licence | The licence for the Player SDK that decrypts Wandura films, tied to your app IDs. Your organisation pays for it. | The iOS bundle ID and Android package name your app will ship with, not temporary ones. | How roles work on the portal is explained in [Roles](../partners/roles.md). ⋯ Licence dates are whole days in UTC, and both the first and the last day are included. 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 playback key and the Player SDK licence, and your contact has confirmed the list of licensed films. + **Done when:** your developers can sign in to partner.wandura.ai and open **Developers**, you have received the playback key and the Player SDK licence, and Wandura has confirmed the list of licensed films. ## Phase 1: Keys and environments {#phase-1} ⋯ ### How often {#sync-frequency} - Run the job every 15 to 60 minutes, and let someone trigger it by hand when your contact 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. + 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 {#no-pagination} ⋯ 4. Stop using a creative once its `rights.ends_at` has passed. 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 your Wandura partner contact how final video files reach your systems. Details: [Creatives](concepts/creatives.md). + Records describe each creative and never include a media URL. Ask Wandura how final video files reach your systems. Details: [Creatives](concepts/creatives.md). ## Phase 5: Test plan {#phase-5} ⋯ **Catalog** - - [ ] The films in the app match the licence list confirmed by your Wandura contact. + - [ ] 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. ⋯ **Rights ending** - - [ ] Ask your Wandura contact to end the licence of one test film. 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". + - [ ] Ask Wandura to end the licence of one test film. 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. ⋯ - [ ] 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. - - [ ] Your Wandura contact has confirmed the licensed films and their start and end dates. + - [ ] Wandura has confirmed the licensed films and their start and end dates. - [ ] The catalog sync job runs on schedule in production, with an alert on failure. - [ ] The paywall reads `free_until_episode` from your synced catalog. ⋯ | Ticket success rate, and answers by `error_code` | Your backend metrics | A jump in `not_entitled` usually means a licence ended; in `invalid_device_info` or `sdk_required`, that an app release broke the Player SDK wiring; in `rate_limited`, a retry loop. | | `5xx` answers and ticket latency | Your backend metrics | Retry with backoff, and tell Wandura if it lasts. | - | Last successful catalog sync, number of films and of playable episodes | Your sync job | A stalled job keeps showing withdrawn titles; a sudden drop is worth a message to your contact. | + | Last successful catalog sync, number of films and of playable episodes | Your sync job | A stalled job keeps showing withdrawn titles; a sudden drop is worth a message to Wandura. | | "Last used" of each key | **Developers** page | Finds unused keys you can revoke. | ⋯ | Need | Contact | |---|---| - | Organisation setup, playback keys and their rotation, film licences and dates, the Player SDK licence, a rights-end test | Your Wandura partner contact | + | Organisation setup, playback keys and their rotation, film licences and dates, the Player SDK licence, a rights-end test | Wandura | | The **Developer** role for a new developer | Your organisation Admin on partner.wandura.ai | | Keys you create yourself (`metadata:read`, `creatives:export`) | Your developers, on the **Developers** page | - | A playback key that may have leaked | Your organisation Admin revokes it first, then tells your Wandura partner contact | - | Repeated `5xx` answers or other outages | Your Wandura partner contact, with the details listed in [Support](help/support.md) | + | A playback key that may have leaked | Your organisation Admin revokes it first, then tells Wandura | + | Repeated `5xx` answers or other outages | Wandura, with the details listed in [Support](help/support.md) | ## Related ⋯
- 30 Sept 2026 · +1 −1 lines
Show changes
# 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](#go-live-checklist). Other model? See [Choose an integration model](integration-models.md). + > **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](#go-live-checklist). Other model? See [Choose an integration model](integration-models.md). Checklist and licence price: [Before you start](before-you-start.md). 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. ⋯
- 30 Sept 2026 · +1 −1 lines
Show changes
# 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](#go-live-checklist). + > **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](#go-live-checklist). Other model? See [Choose an integration model](integration-models.md). 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. ⋯
- 29 Sept 2026 · +2 −0 lines
Show changes
# 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](#go-live-checklist). + 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. ⋯
- 29 Sept 2026 · Page created