1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.android.settings.overlay;
17 
18 import android.app.Activity;
19 import android.content.BroadcastReceiver;
20 import android.content.Context;
21 
22 import androidx.annotation.Nullable;
23 import androidx.localbroadcastmanager.content.LocalBroadcastManager;
24 
25 /**
26  * An interface for classes wishing to provide the ability to serve surveys to implement.
27  */
28 public interface SurveyFeatureProvider {
29     /**
30      * Downloads a survey asynchronously to shared preferences to be served at a later date.
31      *
32      * @param activity A valid context.
33      * @param surveyId A unique Id representing a survey to download.
34      * @param data     a text blob to be attached to the survey results.
35      * @deprecated This is not used after T.
36      */
37     @Deprecated
downloadSurvey(Activity activity, String surveyId, @Nullable String data)38     void downloadSurvey(Activity activity, String surveyId, @Nullable String data);
39 
40     /**
41      * Shows a previously downloaded survey/prompt if possible in the activity provided.
42      *
43      * @param activity The host activity to show the survey in.
44      * @param surveyId A unique Id representing a survey to download.
45      * @return A boolean indicating if a survey was shown or not.
46      * @deprecated This is not used after T.
47      */
48     @Deprecated
showSurveyIfAvailable(Activity activity, String surveyId)49     boolean showSurveyIfAvailable(Activity activity, String surveyId);
50 
51     /**
52      * A helper method to get the surveyId. Implementers should create a mapping of
53      * keys to surveyIds and provide them via this function.
54      *
55      * @param context   A valid context.
56      * @param simpleKey The simple name of the key to get the surveyId for.
57      * @return The unique Id as a string or null on error.
58      * @deprecated This is not used after T.
59      */
60     @Deprecated
getSurveyId(Context context, String simpleKey)61     String getSurveyId(Context context, String simpleKey);
62 
63     /**
64      * Removes the survey for {@code siteId} if it expired, then returns the expiration date (as a
65      * unix timestamp) for the remaining survey should it exist and be ready to show. Returns -1 if
66      * no valid survey exists after removing the potentially expired one.
67      *
68      * @param context  the calling context.
69      * @param surveyId the site ID.
70      * @return the unix timestamp for the available survey for the given {@coe siteId} or -1 if
71      * there is none available.
72      * @deprecated This is not used after T.
73      */
74     @Deprecated
getSurveyExpirationDate(Context context, String surveyId)75     long getSurveyExpirationDate(Context context, String surveyId);
76 
77     /**
78      * Registers an activity to show surveys/prompts as soon as they are downloaded. The receiver
79      * should be unregistered prior to destroying the activity to avoid undefined behavior by
80      * calling {@link #unregisterReceiver(Activity, BroadcastReceiver)}.
81      *
82      * @param activity The activity that should show surveys once they are downloaded.
83      * @return the broadcast receiver listening for survey downloads. Must be unregistered before
84      * leaving the activity.
85      * @deprecated This is not used after T.
86      */
87     @Deprecated
createAndRegisterReceiver(Activity activity)88     BroadcastReceiver createAndRegisterReceiver(Activity activity);
89 
90     /**
91      * Unregisters the broadcast receiver for this activity. Should only be called once per activity
92      * after a call to {@link #createAndRegisterReceiver(Activity)}.
93      *
94      * @param activity The activity that was used to register the BroadcastReceiver.
95      * @deprecated This is not used after T.
96      */
97     @Deprecated
unregisterReceiver(Activity activity, BroadcastReceiver receiver)98     static void unregisterReceiver(Activity activity, BroadcastReceiver receiver) {
99         if (activity == null) {
100             throw new IllegalStateException("Cannot unregister receiver if activity is null");
101         }
102 
103         LocalBroadcastManager.getInstance(activity).unregisterReceiver(receiver);
104     }
105 
106     /**
107      * Send the visited activity to the place where it will trigger a survey if possible.
108      *
109      * @param simpleKey The simple name of the key to get the surveyId for.
110      */
sendActivityIfAvailable(String simpleKey)111     void sendActivityIfAvailable(String simpleKey);
112 }
113