-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #345 from apivideo/swift-player-analytics-feature/…
…new-analytics [SDK README - api.video-swift-player-analytics] chore(*): move to analytics endpoint v2
- Loading branch information
Showing
1 changed file
with
29 additions
and
209 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,258 +1,78 @@ | ||
| --- | ||
| ## THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT. IF YOU NEED TO CHANGE THIS FILE, CREATE A PR IN THE SOURCE REPOSITORY. | ||
| title: api.video Swift Player | ||
| meta: | ||
| description: The official api.video Swift Player component for api.video. [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app. | ||
| title: api.video Swift player analytics | ||
| meta: | ||
| description: The official api.video Swift player analytics library for api.video. [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app. | ||
| --- | ||
|
|
||
| # api.video Swift Player | ||
|
|
||
| [api.video](https://api.video/) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app. | ||
|
|
||
| ## Project description | ||
|
|
||
| Easily integrate a video player for videos from [api.video](https://api.video) in your Swift | ||
| application. | ||
|
|
||
|  | ||
| This library send player events from the player to api.video. | ||
|
|
||
| ## Getting started | ||
|
|
||
| ### Installation | ||
|
|
||
| #### Swift Package Manager | ||
|
|
||
| In the Project Navigator select your own project. Then select the project in the Project section and click on the | ||
| Package Dependencies tab. Click on the "+" button at the bottom. Paste the below url on the search bar on the top right. | ||
| Finaly click on "Add package" button. | ||
|
|
||
| ``` | ||
| https://github.com/apivideo/api.video-swift-player | ||
| ``` | ||
|
|
||
| Or add this in your Package.swift | ||
| Add the following dependency to your `Package.swift` file: | ||
|
|
||
| ``` | ||
| ```swift | ||
| dependencies: [ | ||
| .package(url: "https://github.com/apivideo/api.video-swift-player.git", from: "1.1.4"), | ||
| .package(url: "https://github.com/apivideo/api.video-swift-player-analytics.git", from: "2.0.0"), | ||
| ], | ||
| ``` | ||
|
|
||
| #### Cocoapods | ||
|
|
||
| Add `pod 'ApiVideoPlayer', '1.1.4'` in your `Podfile` | ||
|
|
||
| Run `pod install` | ||
|
|
||
| ### Retrieve your video Id | ||
|
|
||
| At this point, you must have uploaded a least one video to your account. If you haven't | ||
| see [how to upload a video](https://docs.api.video/vod/upload-a-video-regular-upload/). You'll need | ||
| a video Id to use this component and play a video from api.video. To get yours, follow these steps: | ||
|
|
||
| 1. [Log into your account](https://dashboard.api.video/login) or create | ||
| one [here](https://dashboard.api.video/register). | ||
| 2. Copy your API key (sandbox or production if you are subscribed to one of | ||
| our [plan](https://api.video/pricing)). | ||
| 3. Go to [the official api.video documentation](https://docs.api.video/). | ||
| 4. Go to API Reference -> Videos -> [List all videos](https://docs.api.video/reference/api/Videos#list-all-video-objects) | ||
| 5. Create a `get` request to the `/videos` endpoint based on the reference, using a tool like Postman. | ||
| 6. Copy the "videoId" value of one of elements of the API response. | ||
|
|
||
| Alternatively, you can find your video Id in the video details of | ||
| your [dashboard](https://dashboard.api.video). | ||
|
|
||
| ### Usage | ||
|
|
||
| 1. Imports the library | ||
|
|
||
| ``` | ||
| import ApiVideoPlayer | ||
| ``` | ||
|
|
||
| 2. Instantiates the player view | ||
| #### CocoaPods | ||
|
|
||
| ```swift | ||
| let playerView: ApiVideoPlayerView = ApiVideoPlayerView(frame: .zero, videoOptions: VideoOptions(videoId: "YOUR_VIDEO_ID", videoType: .vod)) // for private video VideoOptions(videoId: "YOUR_VIDEO_ID", videoType: .vod, token: "YOUR_PRIVATE_VIDEO_TOKEN") | ||
| ``` | ||
| Add the following line to your `Podfile`: | ||
|
|
||
| 3. Adds the player view as a subview of your view controller | ||
|
|
||
| ```swift | ||
| override func viewDidLoad() { | ||
| ... | ||
| self.addSubview(playerView) | ||
| } | ||
| ```ruby | ||
| pod 'ApiVideoPlayerAnalytics', '~> 2.0.0 | ||
| ``` | ||
| 4. Delegates the player events | ||
|
|
||
| To be able to use the player delegate, you must implement the PlayerDelegate protocol. | ||
|
|
||
| ```swift | ||
| extension YourViewController: PlayerDelegate { | ||
| public func didPrepare() { | ||
| // Do what you want when didPrepare is called | ||
| } | ||
|
|
||
| public func didReady() { | ||
| // Do what you want when didReady is called | ||
| } | ||
|
|
||
| public func didPause() { | ||
| // Do what you want when didPause is called | ||
| } | ||
|
|
||
| public func didPlay() { | ||
| // Do what you want when didPlay is called | ||
| } | ||
|
|
||
| public func didReplay() { | ||
| // Do what you want when didReplay is called | ||
| } | ||
|
|
||
| public func didMute() { | ||
| // Do what you want when didMute is called | ||
| } | ||
| Then, run `pod install`. | ||
| public func didUnMute() { | ||
| // Do what you want when didUnMute is called | ||
| } | ||
| ### Code sample | ||
| public func didLoop() { | ||
| // Do what you want when didLoop is called | ||
| } | ||
|
|
||
| public func didSetVolume(_: Float) { | ||
| // Do what you want when didSetVolume is called | ||
| } | ||
|
|
||
| public func didSeek(_: CMTime, _: CMTime) { | ||
| // Do what you want when didSeek is called | ||
| } | ||
|
|
||
| public func didEnd() { | ||
| // Do what you want when didEnd is called | ||
| } | ||
|
|
||
| public func didError(_: Error) { | ||
| // Do what you want when didError is called | ||
| } | ||
|
|
||
| public func didVideoSizeChanged(_: CGSize) { | ||
| // Do what you want when didVideoSizeChanged is called | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 5. Registers the delegate | ||
| Create a `ApiVideoAnalyticsAVPlayer` instance. | ||
| ```swift | ||
| override func viewDidLoad() { | ||
| ... | ||
| self.playerView.addDelegate(self) | ||
| } | ||
| ``` | ||
| import ApiVideoPlayerAnalytics | ||
| 6. To use fullscreen, you must pass the view controller to the player view | ||
|
|
||
| ```swift | ||
| override func viewDidAppear(_ animated: Bool) { | ||
| ... | ||
| playerView.viewController = self | ||
| } | ||
| let player = ApiVideoAnalyticsAVPlayer(url: "URL of the HLS manifest") // HLS manifest from api.video. Example: https://vod.api.video/vod/YOUR_VIDEO_ID/hls/manifest.m3u8 | ||
| ``` | ||
| #### Remote control | ||
|
|
||
| If you want to enable the remote control do the following: | ||
| Then, use it like a regular `AVPlayer`. | ||
| ```swift | ||
| override func viewDidLoad() { | ||
| ... | ||
| self.playerView.enableRemoteControl = true | ||
| } | ||
| player.play() | ||
| ``` | ||
| When you have to remove it set `enableRemoteControl` to false | ||
|
|
||
| By default the remote control is hidden. | ||
|
|
||
| #### Supported player views | ||
|
|
||
| The api.video Swift player comes with a specific view `ApiVideoPlayerView` to display the video | ||
| and its controller. If you require a customization of this view such as changing a button color,..., | ||
| you can contact [us](https://github.com/apivideo/api.video-swift-player/issues). | ||
|
|
||
| Otherwise, in the `ApiVideoPlayerController`, you can also use the following views: | ||
|
|
||
| - [`AVPlayerViewController`](https://developer.apple.com/documentation/avkit/avplayerviewcontroller): AVKit view | ||
| For a custom domain collector, use: | ||
| ```swift | ||
| // Create the api.video controller | ||
| let controller = ApiVideoPlayerController( | ||
| videoOptions: VideoOptions(videoId: "vi77Dgk0F8eLwaFOtC5870yn", videoType: .vod), | ||
| delegates: [], | ||
| autoplay: false | ||
| ) | ||
| // Create the AVKit AVPlayerViewController | ||
| let viewController = AVPlayerViewController() | ||
|
|
||
| /// Pass the api.video controller to the AVKit AVPlayerViewController | ||
| viewController.setApiVideoPlayerController(controller) | ||
| // Prepare the view | ||
| self.addChild(viewController) | ||
| view.addSubview(viewController.view) | ||
| // Set the AVKit AVPlayerViewController frame size according to your needs (here it's the whole screen) | ||
| viewController.view.frame = self.view.frame | ||
| // Do what you want with the video controller (play, pause, seek,...) | ||
| controller.play() | ||
| let player = ApiVideoAnalyticsAVPlayer(url: "URL of the HLS manifest", collectorUrl: "https://collector.mycustomdomain.com") // Register the player analytics listener so it sends player events to api.video. | ||
| ``` | ||
| - [`AVPlayerLayer`](https://developer.apple.com/documentation/avfoundation/avplayerlayer). A view that only display the video. It requires more work to be used. | ||
|
|
||
| ### Play an api.video video in your AVPlayer | ||
| ## Documentation | ||
| If you are using AVPlayer directly, you can use the api.video Swift extensions: | ||
| // TODO | ||
| 1. Create a video | ||
| ## Sample application | ||
| ```swift | ||
| let videoOptions = VideoOptions(videoId: "YOUR_VIDEO_ID", videoType: .vod)) | ||
| // for private video VideoOptions(videoId: "YOUR_VIDEO_ID", videoType: .vod, token: "YOUR_PRIVATE_VIDEO_TOKEN") | ||
| ``` | ||
| Open `ApiVideoPlayerAnalytics.xcodeproj`. | ||
| 2. Pass it to your AVPlayer | ||
| Replace the default media ID in `Examples/iOS/ViewController.swift` with your own. | ||
| ```swift | ||
| val player = AVPlayer() // You already have that in your code | ||
| avPlayer.replaceCurrentItem(withHls: videoOptions) | ||
| let url = Utils.inferManifestURL(mediaId: "vi77Dgk0F8eLwaFOtC5870yn") // replace `vi77Dgk0F8eLwaFOtC5870yn` with your own media ID | ||
| ``` | ||
| ## Sample application | ||
|
|
||
| A demo application demonstrates how to use player. | ||
| See [`/example`](https://github.com/apivideo/api.video-swift-player/tree/main/Examples) | ||
| folder. | ||
|
|
||
| On the first run, you will have to set your video Id: | ||
|
|
||
| 1. Replace "YOUR_VIDEO_ID" by your video Id | ||
|
|
||
| ## Documentation | ||
|
|
||
| - [Player documentation](https://apivideo.github.io/api.video-swift-player/documentation/apivideoplayer/) | ||
| - [api.video documentation](https://docs.api.video) | ||
|
|
||
| ## Dependencies | ||
|
|
||
| We are using external library | ||
|
|
||
| | Plugin | README | | ||
| | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | ||
| | [ApiVideoPlayerAnalytics](https://github.com/apivideo/api.video-swift-player-analytics) | [README.md](https://github.com/apivideo/api.video-swift-player-analytics#readme) | | ||
| Then, run the `Example iOS` target. | ||
| ## FAQ | ||
| If you have any questions, ask us here: [https://community.api.video](https://community.api.video) or | ||
| use [Issues](https://github.com/apivideo/api.video-swift-player/issues). | ||
| If you have any questions, ask us in the [community](https://community.api.video) or | ||
| use [issues](https://github.com/apivideo/api.video-swift-player-analytics/issues). |