/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.support.app.recommendation; import android.app.Notification; import android.os.Bundle; /** *

* Helper class to add content info extensions to notifications. To create a notification with * content info extensions: *

    *
  1. Create an {@link Notification.Builder}, setting any desired properties. *
  2. Create a {@link RecommendationExtender}. *
  3. Set content info specific properties using the {@code add} and {@code set} methods of * {@link RecommendationExtender}. *
  4. Call {@link android.app.Notification.Builder#extend(Notification.Extender) * Notification.Builder.extend(Notification.Extender)} to apply the extensions to a notification. *
* *
Notification notification = new Notification.Builder(context) * ... * .extend(new RecommendationExtender() * .set*(...)) * .build(); * 
*

* Content info extensions can be accessed on an existing notification by using the * {@code RecommendationExtender(Notification)} constructor, and then using the {@code get} methods * to access values. */ public final class RecommendationExtender implements Notification.Extender { private static final String TAG = "RecommendationExtender"; // Key for the Content info extensions bundle in the main Notification extras bundle private static final String EXTRA_CONTENT_INFO_EXTENDER = "android.CONTENT_INFO_EXTENSIONS"; // Keys within EXTRA_CONTENT_INFO_EXTENDER for individual content info options. private static final String KEY_CONTENT_TYPE = "android.contentType"; private static final String KEY_CONTENT_GENRES = "android.contentGenre"; private static final String KEY_CONTENT_PRICING_TYPE = "android.contentPricing.type"; private static final String KEY_CONTENT_PRICING_VALUE = "android.contentPricing.value"; private static final String KEY_CONTENT_STATUS = "android.contentStatus"; private static final String KEY_CONTENT_MATURITY_RATING = "android.contentMaturity"; private static final String KEY_CONTENT_RUN_LENGTH = "android.contentLength"; private String[] mTypes; private String[] mGenres; private String mPricingType; private String mPricingValue; private int mContentStatus = -1; private String mMaturityRating; private long mRunLength = -1; /** * Create a {@link RecommendationExtender} with default options. */ public RecommendationExtender() { } /** * Create a {@link RecommendationExtender} from the RecommendationExtender options of an * existing Notification. * * @param notif The notification from which to copy options. */ public RecommendationExtender(Notification notif) { Bundle contentBundle = notif.extras == null ? null : notif.extras.getBundle(EXTRA_CONTENT_INFO_EXTENDER); if (contentBundle != null) { mTypes = contentBundle.getStringArray(KEY_CONTENT_TYPE); mGenres = contentBundle.getStringArray(KEY_CONTENT_GENRES); mPricingType = contentBundle.getString(KEY_CONTENT_PRICING_TYPE); mPricingValue = contentBundle.getString(KEY_CONTENT_PRICING_VALUE); mContentStatus = contentBundle.getInt(KEY_CONTENT_STATUS, -1); mMaturityRating = contentBundle.getString(KEY_CONTENT_MATURITY_RATING); mRunLength = contentBundle.getLong(KEY_CONTENT_RUN_LENGTH, -1); } } /** * Apply content extensions to a notification that is being built. This is typically called by * the {@link android.app.Notification.Builder#extend(Notification.Extender) * Notification.Builder.extend(Notification.Extender)} method of {@link Notification.Builder}. */ @Override public Notification.Builder extend(Notification.Builder builder) { Bundle contentBundle = new Bundle(); if (mTypes != null) { contentBundle.putStringArray(KEY_CONTENT_TYPE, mTypes); } if (mGenres != null) { contentBundle.putStringArray(KEY_CONTENT_GENRES, mGenres); } if (mPricingType != null) { contentBundle.putString(KEY_CONTENT_PRICING_TYPE, mPricingType); } if (mPricingValue != null) { contentBundle.putString(KEY_CONTENT_PRICING_VALUE, mPricingValue); } if (mContentStatus != -1) { contentBundle.putInt(KEY_CONTENT_STATUS, mContentStatus); } if (mMaturityRating != null) { contentBundle.putString(KEY_CONTENT_MATURITY_RATING, mMaturityRating); } if (mRunLength > 0) { contentBundle.putLong(KEY_CONTENT_RUN_LENGTH, mRunLength); } builder.getExtras().putBundle(EXTRA_CONTENT_INFO_EXTENDER, contentBundle); return builder; } /** * Sets the content types associated with the notification content. The first tag entry will be * considered the primary type for the content and will be used for ranking purposes. Other * secondary type tags may be provided, if applicable, and may be used for filtering purposes. * * @param types Array of predefined type tags (see the CONTENT_TYPE_* constants) * that describe the content referred to by a notification. */ public RecommendationExtender setContentTypes(String[] types) { mTypes = types; return this; } /** * Returns an array containing the content types that describe the content associated with the * notification. The first tag entry is considered the primary type for the content, and is used * for content ranking purposes. * * @return An array of predefined type tags (see the CONTENT_TYPE_* constants) that * describe the content associated with the notification. * @see RecommendationExtender#setContentTypes */ public String[] getContentTypes() { return mTypes; } /** * Returns the primary content type tag for the content associated with the notification. * * @return A predefined type tag (see the CONTENT_TYPE_* constants) indicating the * primary type for the content associated with the notification. * @see RecommendationExtender#setContentTypes */ public String getPrimaryContentType() { if (mTypes == null || mTypes.length == 0) { return null; } return mTypes[0]; } /** * Sets the content genres associated with the notification content. These genres may be used * for content ranking. Genres are open ended String tags. *

* Some examples: "comedy", "action", "dance", "electronica", "racing", etc. * * @param genres Array of genre string tags that describe the content referred to by a * notification. */ public RecommendationExtender setGenres(String[] genres) { mGenres = genres; return this; } /** * Returns an array containing the content genres that describe the content associated with the * notification. * * @return An array of genre tags that describe the content associated with the notification. * @see RecommendationExtender#setGenres */ public String[] getGenres() { return mGenres; } /** * Sets the pricing and availability information for the content associated with the * notification. The provided information will indicate the access model for the content (free, * rental, purchase or subscription) and the price value (if not free). * * @param priceType Pricing type for this content. Must be one of the predefined pricing type * tags (see the CONTENT_PRICING_* constants). * @param priceValue A string containing a representation of the content price in the current * locale and currency. * @return This object for method chaining. */ public RecommendationExtender setPricingInformation( @ContentRecommendation.ContentPricing String priceType, String priceValue) { mPricingType = priceType; mPricingValue = priceValue; return this; } /** * Gets the pricing type for the content associated with the notification. * * @return A predefined tag indicating the pricing type for the content (see the CONTENT_PRICING_* * constants). * @see RecommendationExtender#setPricingInformation */ public String getPricingType() { return mPricingType; } /** * Gets the price value (when applicable) for the content associated with a notification. The * value will be provided as a String containing the price in the appropriate currency for the * current locale. * * @return A string containing a representation of the content price in the current locale and * currency. * @see RecommendationExtender#setPricingInformation */ public String getPricingValue() { if (mPricingType == null) { return null; } return mPricingValue; } /** * Sets the availability status for the content associated with the notification. This status * indicates whether the referred content is ready to be consumed on the device, or if the user * must first purchase, rent, subscribe to, or download the content. * * @param contentStatus The status value for this content. Must be one of the predefined content * status values (see the CONTENT_STATUS_* constants). */ public RecommendationExtender setStatus( @ContentRecommendation.ContentStatus int contentStatus) { mContentStatus = contentStatus; return this; } /** * Returns status value for the content associated with the notification. This status indicates * whether the referred content is ready to be consumed on the device, or if the user must first * purchase, rent, subscribe to, or download the content. * * @return The status value for this content, or -1 is a valid status has not been specified * (see the CONTENT_STATUS_* for the defined valid status values). * @see RecommendationExtender#setStatus */ public int getStatus() { return mContentStatus; } /** * Sets the maturity level rating for the content associated with the notification. * * @param maturityRating A tag indicating the maturity level rating for the content. This tag * must be one of the predefined maturity rating tags (see the CONTENT_MATURITY_* * constants). */ public RecommendationExtender setMaturityRating( @ContentRecommendation.ContentMaturity String maturityRating) { mMaturityRating = maturityRating; return this; } /** * Returns the maturity level rating for the content associated with the notification. * * @return returns a predefined tag indicating the maturity level rating for the content (see * the CONTENT_MATURITY_* constants). * @see RecommendationExtender#setMaturityRating */ public String getMaturityRating() { return mMaturityRating; } /** * Sets the running time (when applicable) for the content associated with the notification. * * @param length The runing time, in seconds, of the content associated with the notification. */ public RecommendationExtender setRunningTime(long length) { if (length < 0) { throw new IllegalArgumentException("Invalid value for Running Time"); } mRunLength = length; return this; } /** * Returns the running time for the content associated with the notification. * * @return The running time, in seconds, of the content associated with the notification. * @see RecommendationExtender#setRunningTime */ public long getRunningTime() { return mRunLength; } }