Android Widget

Basic Integration

Make the following changes to your Projects build.gradle

...
allprojects{
    repositories{
        maven { url "https://www.myget.org/F/3qnexx/maven" }
    }
}
...

add the following dependencies

dependencies { 
    implementation "tv.nexx.android:widget:2.+"
}

Configure the Widget by adding the following Settings to your values/strings.xml:

<resources>
    <string name="widget_domain" translatable="false">YOUR_DOMAIN_ID</string>
    <string name="widget_feed_hash" translatable="false">YOUR_FEED_HASH</string>
    <string name="widget_launchactivity" translatable="false">YOUR_LAUNCH_ACTIVITY</string>
    
    <!-- only needed, if the Feed is secured with a Secret -->
    <string name="widget_feed_secret" translatable="false">YOUR_FEED_SECRET</string>
    <!-- this Parameter can be obtained from 3Q nexx or nexxOMNIA -->
    <string name="widget_app" translatable="false">YOUR_APP_ID</string>
    <!-- only needed for android 12+ -->
    <string name="widget_description">Widget Description</string>
</resources>

Handle the System Intents by adding a receiver to src/main/AndroidManifest.xml:

<receiver
  android:name="tv.nexx.android.widget.Widget"
  android:exported="true">
  <intent-filter>
    <action android:name="android.appwidget.action.APPWIDGET_UPDATE"/>
  </intent-filter>
</receiver>

Prepare the necessary Image Assets (Icon and Preview PNGs) and place them under src/main/res/drawable/

Asset	Dimensions	Usage
widget_icon.png	512x512px	Icon to be shown on the Widget as App Reference
widget_preview.png	660x400px	Icon for Widget Selection Dialogue in android

Handling Intent

Once a User clicks on any Item of the Widget, the App is called directly (if the receiver has been configured correctly).

The App now is responsable to collect all necessary details in order to navigate to the Target of this Intent:

...
@Override
public void onCreate(Bundle savedInstanceState) {
        Intent intent = getIntent();
        if (intent != null) {
                 String action = intent.getAction();
                 //make sure, this Intent comes from the Widget
                 if(action.equals("tv.nexx.android.widget.OPEN"){
                          //the Widget sends all available Item Identifiers in the Extra Bundle for easy access.
                          appDoNavigate(intent.getStringExtra("streamtype"), intent.getStringExtra("itemID"));         
                 }
        }
}

The available Item Identifiers are:

• itemID

• itemHash

• globalID

• refnr

• slug

• link (if configured in nexxOMNIA)

• domainID

• streamtype

Enhanced Methods

It is possible to update/refresh/reconfigure all Widget Instances from your App directly with the following Methods:

import tv.nexx.android.widget.Widget;
import tv.nexx.android.widget.WidgetConfiguration;

public class MainActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        
        Widget widget = new Widget();
        
        //simple force all Widget Instances to refresh the Feed
        widget.updateWidgets(this.getContext());
        
        //update the Configuration and refresh the Feed
        WidgetConfiguration config=new WidgetConfiguration(
            new HashMap<String, Object>() {{
               put("language","es");
               put("feedUpdateInterval", 30);
            }}
        );
        widget.updateConfiguration(this.getContext(),config);
    }
}

For a detailed Overview of the Meaning of the given Configuration, please take a look here:

Widget Override Options