API definition

[tralves]

The README.md shall contain the API to interact with the plugin. This will also help defining the scope of the project.

[tralves]

@dseeker Hello! Can you please take a look in the API section of the project's README.md? The text/format can be improved later, but for now I would like to have your OK on the methods that will be implemented for all platforms.

The only thing missing there, I think, is the Picture in Picture functionality because I have to check how it will work on Android before designing a cross-platform API.

Thanks!

[dseeker]

Seems to me the API syntax ended up very iOS centric. This might pose problems when trying to create a unified codebase with the Web/Javascript version of the site. I don't how much you have investigated the Weex Web plugin version, but it's likely you'll have to use the Javascript API for that, so to avoid having a double conversion issue (when using Desktop version) perhaps using the Javascript API as guide would be better. So maybe we should investigate mapping a subset of the javascript API onto the iOS and Android SDK for interoperability.

If you look at the JS Api you'll see it uses all encompassing methods, passing strings as parameters for each command. for example:

this.$refs.kdp.play() would be this.$refs.kdp.sendNotification("doPlay")

this.$refs.kdp.seek(time) would turn into this.$refs.kdp.sendNotification("doSeek", time);

so instead of prepare loading a media configt, the API would be this.$refs.kdp.sendNotification("changeMedia", { "entryId" : "0_wm82kqmm" }); and the plugin would work the methods and configuration necessary to execute this API request.

Regarding Events, I think that's more flexible, since in JS we have to bind an event listener to a function, so these can have the native iOS names and the mapping for Desktop has to be done anyway, so it can be mapped to the same functions. so for example http://player.kaltura.com/docs/api#playerPlayEnd, in JS I could write this.$refs.kdp.addJsListener('playerPlayEnd', this.$refs.kdp.onEnded)

It would be helpful to have some way where after this first version of the component is functional, there was an easy way to expand events to allow compatibility with other events. For example, we're currently using the event "firstPlay" on the JS player, and AFAIK this doesn't exist natively on iOS. But we could implement a simple logic to check if the play event, after media has changed, is being fired for the first time or not, then this could fire an additional "mock" event from the weex-plugin, to conform with the JS API. This of course is not needed ATM, it's just good to keep in mind we will probably have more events than what the KDP SDK currently has, and there should be an easy way to expand this on the weex-kdp plugin for each platform.

What are your thoughts? Am I missing anything else?

[tralves]

Hi!

The concern about the web API is valid. The API you are proposing would simplify the Web implementation. The thing is that I would have to write a wrapper around the JS API anyway. So, it would be simpler to write it the way you mentioned but it is not impossible to implement the way I propose.

I think in the end we should reach for the best API design. An API based on string notifications and string events allows the consumer to do some cool stuff like listening to multiple events in the same function. I would prefer a more expressive API like the one I was writing, but I don't have many reasons for it other than preference of style and expressiveness.

@dseeker, you are the closest thing I have for a consumer of the API, since you have been writing this kind of integrations with video components. So I give you back the question: which API will you prefer using in the app? Consider that everything is doable.

I was looking at other video APIs (Vimeo and Youtube) and saw a bit of everything. Both Vimeo and Youtube use string events on JS API (e.g. player.on('stopped', callback) or player.player.addEventListener(), but they use different listeners on the native APIs...

[dseeker]

@tralves the important thing is harmonize all api request across the tech stack. And because the Web API uses the string events, It makes more sense to me to normalize the iOS/Android to the web, than to write adapters for the web into the more restricted api of iOS/Android

I have a soft deadline for an internal working prototype for the 15th, do you think it's possible to have a preview version of the component with simple load/play/pause by the end of the week? If not I will fallback to the web iframe like I was before

[tralves]

Ok! I'll change the api to use string events (this.$refs.kdp.addJsListener()) and string commands (this.$refs.kdp.sendNotification()). Is this correct?

About the soft launch, you need it for all platforms (iOS, Android and Web)? The Android will be harder, since I am traveling back to Portugal this week. It is not impossible, though.

[dseeker]

the goal is still to have the iOS first. But I'm also making a usable Android version for that date. It will fallback to the webview and once the Android plugin can also start being used it will supersede the webview. I would prioritize getting iOS working then we see if there is time for Android for the short notice, early version

[tralves]

@dseeker Please check the README.md for the overall structure of the API. Actual function names/strings, etc may change as I add more platforms. If it is ok, we can close this issue.