Welcome Developers and Content Owners!

TiviApp-related code, utilities and repository to be used by third-party developers

Welcome Developers and Content Owners!

This GitHub page contains all the information you need for creating and managing your own TiviApp Content Provider. Here you will find:

If you are still not fimiliar with the TiviApp application, please visit our website or just download it from Google Play.

Introduction

A Content Provider is basically a third-party piece of code (sometimes called a “plugin” or “addon”) that can provide usefull content for TiviApp users. This content can be either:

There are three types of Providers that are currently supported by TiviApp:

A Provider can be also viewed as a small server that handles various requests from the TiviApp client. Therefore your code should be designed and developed according to the following basic principles:

Getting Started

The simpliest way of getting started is to clone this repository and start exploring the demo projects. The following sections will guide you through the neccessary steps for getting the “Hello World” projects up and running on your machine. So use your favorite Git client to clone this repository at: https://github.com/montezumba/TiviAppDev.git and let’s get started!

Android Provider

This type of provider is the most powerfull option and is best suited for Android Developers who wish to add some non-trivial logic that should be executed on a native environment. For this, you will need to have some knowledge on developing Android applications and the following environment set up:

After clonning the repository (for example to: C:\TiviAppDev), just follow these steps:

  1. Open Android Studio and select “Open an existing Android Project”
  2. Select the HelloWorld project at C:\TiviAppDev\HelloWorld
  3. If a message appears that request further configuration, click on “Configure” image
  4. Build the project and run it on your Android device or emulator.
  5. This project has no default Activity, so you shouldn’t see anything running after clicking on “Run”
  6. Open TiviApp, choose “Settings” and select the “Providers” tab. You should see the following new Provider in that list: Image Image

Each Content Provider is hosted on a repository (server for example), which is described by a special JSON file. TiviApp has one such repository embedded within the main application - the Official TiviApp Repository. If your Provider is not hosted there, the user should explicitly add your repository by providing the path to the corresponding JSON. (see below)

Web Provider

This type of provider is suited for quick and simple content providers (usually ones that already have a website or an IPTV server running). To setup a Web Provider you will need some basic knowledge in web development, specifically in javascript. A typical Web Provider consists of the following two files:

  1. A Virtual Repo file (see below for more details). This file will usually have the *.json extenssion (or php/aspx for server-generated repos) and point to one or more Web Provider files
  2. A Web Provider file (usually with html/js/php/aspx extenssion) that holds the server logic and retrieves playlists/EPG.

In the “HelloWorldWeb” project we have prepared three demo files to illustrate each type and how they are connected with one another:

  1. Virtual Repo File that can be accessed globally at: https://montezumba.github.io/TiviAppDev/HelloWorldWeb/hello_world.json
  2. Web Provider File that can be accessed globally at: https://montezumba.github.io/TiviAppDev/HelloWorldWeb/hello_world.html
  3. A demo playlist file that can be accessed globally at: https://montezumba.github.io/TiviAppDev/HelloWorldWeb/hello_world.m3u

To add this provider to TiviApp, just follow these simple steps:

  1. Open TiviApp and go to “Settings”
  2. Select the “Providers” tab
  3. CLick on the “+” button to add a new Provider
  4. Enter the URL for the Virtual Repo file (see above) and click “OK”. Image The Provider info, playlist(s) and TV Guide(s) should appear in the corresponding tabs: Image Image

Development

In this section we will provide an overview the basic concepts of Provider Development. We assume here that you already cloned this repo and you know how to build and run the corresponding demo projects. The basic sequence is very simple:

  1. The TiviApp client sends a request with the following parameters: * Request Id - a unique identifier for this request.
    • Proc - the request type. Can be either: “request_live_playlist”, “request_tvguide” or “request_live_url”.
    • Query - optional query string for this request (for example: requested language).
  2. Your server responds to each client by retrieving the following data: * Request Id - the id of the corresponding request
    • For “Playlist Request”: the response should contain the name of the playlist and its URL
    • For “TV Guide Request” : the response should contain the name of the TV Guide, its URL and its validity date
    • For “Live URL Request” : the response should contain the name of the playable stream and its URL

Android Provider

If we explore the demo project we can see the observe the following source files:

The AndroidManifest.xml configuration files should be configured as follows:

 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

android:name="HelloWorldApplication"

<service android:name="HelloWorldService" >

    <intent-filter>
        <action android:name="com.treynix.helloworld.ACTION_ADDON_REQUEST" />
        <action android:name="com.treynix.tiviapp.action.ACTION_PROVIDER_REGISTER" />
        <action android:name="com.treynix.tiviapp.action.ACTION_PROVIDER_KILL" />
    </intent-filter>

    <meta-data android:name="playlist_support" android:value="true"/>
    <meta-data android:name="tvguide_support" android:value="true"/>
    <meta-data android:name="video_support" android:value="true"/>

In the HelloWorldConfig.java you should provide the basic configuration to your provider, based on the following base-constructor arguments:

public HelloWorldConfig() {
		super(	"Hello World Provider",
				5 * Constants.MINUTES,
				5 * Constants.MINUTES,
				10,
				HelloWorldConfig.class.getPackage().getName(),
                null
                );
	}

WARNING: Setting too high values is not recommended. TiviApp has its own timeout mechanism, which will deactivate non-responsive providers. Each provider should detect and handle its own timeouts and errors.

The HelloWorldMain.java handles the main server logic by implementing the following interface methods:

WARNING: All these methods are blocking. Remember: you are implementing a server and the best practice here is to avoid “heavy” logic. However, if you do need perform some blocking operations - use the Worker utility to allow parallel execution.

Web Provider

Working with Web Providers is much more simple. TiviApp has its own, built-in Android Provider that takes care of all the abovementioned configrations. This built-in provider transmits all the requests to third-party “virtual” providers by calling their Web Provider File URL and passing the applicable parameters.

TiviApp provides a WebView API framework to handle incomming events and provide the required outputs. This API can be accessed within your web application by using the TiviProvider javascript object. To handle incomming requests, the Web Provider File should check and parse the following GET parameters:

The response should be sent back to the client by calling the following API methods:

Repository

For both Android and Web Providers you may define a repository file to provide additional meta-data about it. Providing a Repository File is mandatory for Web Providers, since they are used as an input URL for the user that wants to add them to TiviApp.

The Repository File should have the following structure:

{
	"addons":
		[			
			{			
				"name":"Hello World Web",
				"service":"https://montezumba.github.io/TiviAppDev/HelloWorldWeb/hello_world.html",
				"author":"Treynix",
				"description":"A demo Web Provider for demonstrating basic provider capabilities",
				"version":"1",
				"versionName":"0.1",
				"path":"virtual",
				"supportedFeatures": [					
					"playlist_support"								
				]
			}
			
		]
}