1 // Copyright 2018 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef ASH_ASSISTANT_UTIL_DEEP_LINK_UTIL_H_
6 #define ASH_ASSISTANT_UTIL_DEEP_LINK_UTIL_H_
7 
8 #include <map>
9 #include <string>
10 
11 #include "base/component_export.h"
12 #include "base/optional.h"
13 #include "base/timer/timer.h"
14 
15 class GURL;
16 
17 namespace chromeos {
18 namespace assistant {
19 enum class AssistantEntryPoint;
20 enum class AssistantQuerySource;
21 }  // namespace assistant
22 }  // namespace chromeos
23 
24 namespace ash {
25 namespace assistant {
26 namespace util {
27 
28 // Enumeration of deep link types.
29 enum class DeepLinkType {
30   kUnsupported,
31   kAlarmTimer,
32   kChromeSettings,
33   kFeedback,
34   kLists,
35   kNotes,
36   kOnboarding,
37   kProactiveSuggestions,
38   kQuery,
39   kReminders,
40   kScreenshot,
41   kSettings,
42   kTaskManager,
43   kWhatsOnMyScreen,
44 };
45 
46 // Enumeration of deep link parameters.
47 // Examples of usage in comments. Note that actual Assistant deeplinks are
48 // prefixed w/ "googleassistant"; "ga" is only used here to avoid line wrapping.
49 enum class DeepLinkParam {
50   kAction,      // ga://proactive-suggestions?action=cardClick
51   kCategory,    // ga://proactive-suggestions?category=1
52   kClientId,    // ga://reminders?action=edit&clientId=1
53   kDurationMs,  // ga://alarm-timer?action=addTimeToTimer&durationMs=60000
54   kEid,         // ga://lists?eid=1
55   kEntryPoint,  // ga://send-query?q=weather&entryPoint=11
56   kHref,   // ga://proactive-suggestions?action=cardClick&href=https://g.co/
57   kIndex,  // ga://proactive-suggestions?action=cardClick&index=1
58   kId,     // ga://alarm-timer?action=addTimeToTimer&id=1
59   kPage,   // ga://settings?page=googleAssistant
60   kQuery,  // ga://send-query?q=weather
61   kQuerySource,  // ga://send-query?q=weather&querySource=12
62   kRelaunch,     // ga://onboarding?relaunch=true
63   kType,         // ga://lists?id=1&type=shopping
64   kVeId,         // ga://proactive-suggestions?action=cardClick&veId=1
65 };
66 
67 // Enumeration of alarm/timer deep link actions.
68 enum class AlarmTimerAction {
69   kAddTimeToTimer,
70   kPauseTimer,
71   kRemoveAlarmOrTimer,
72   kResumeTimer,
73 };
74 
75 // Enumeration of proactive suggestions deep link actions.
76 enum class ProactiveSuggestionsAction {
77   kCardClick,
78   kEntryPointClick,
79   kEntryPointClose,
80   kViewImpression,
81 };
82 
83 // Enumeration of reminder deep link actions.
84 enum class ReminderAction {
85   kCreate,
86   kEdit,
87 };
88 
89 // Returns a new deep link, having appended or replaced the entry point param
90 // from the original |deep_link| with |entry_point|.
91 COMPONENT_EXPORT(ASSISTANT_UTIL)
92 GURL AppendOrReplaceEntryPointParam(
93     const GURL& deep_link,
94     chromeos::assistant::AssistantEntryPoint entry_point);
95 
96 // Returns a new deep link, having appended or replaced the query source param
97 // from the original |deep_link| with |query_source|.
98 COMPONENT_EXPORT(ASSISTANT_UTIL)
99 GURL AppendOrReplaceQuerySourceParam(
100     const GURL& deep_link,
101     chromeos::assistant::AssistantQuerySource query_source);
102 
103 // Returns a deep link to perform an alarm/timer action.
104 COMPONENT_EXPORT(ASSISTANT_UTIL)
105 base::Optional<GURL> CreateAlarmTimerDeepLink(
106     AlarmTimerAction action,
107     base::Optional<std::string> alarm_timer_id,
108     base::Optional<base::TimeDelta> duration = base::nullopt);
109 
110 // Returns a deep link to send an Assistant query.
111 COMPONENT_EXPORT(ASSISTANT_UTIL)
112 GURL CreateAssistantQueryDeepLink(const std::string& query);
113 
114 // Returns a deep link to top level Assistant Settings.
115 COMPONENT_EXPORT(ASSISTANT_UTIL) GURL CreateAssistantSettingsDeepLink();
116 
117 // Returns a deep link to initiate a screen context interaction.
118 COMPONENT_EXPORT(ASSISTANT_UTIL) GURL CreateWhatsOnMyScreenDeepLink();
119 
120 // Returns the parsed parameters for the specified |deep_link|. If the supplied
121 // argument is not a supported deep link or if no parameters are found, an empty
122 // map is returned.
123 COMPONENT_EXPORT(ASSISTANT_UTIL)
124 std::map<std::string, std::string> GetDeepLinkParams(const GURL& deep_link);
125 
126 // Returns a specific string |param| from the given parameters. If the desired
127 // parameter is not found, and empty value is returned.
128 COMPONENT_EXPORT(ASSISTANT_UTIL)
129 base::Optional<std::string> GetDeepLinkParam(
130     const std::map<std::string, std::string>& params,
131     DeepLinkParam param);
132 
133 // Returns AlarmTimerAction from the given parameters. If the desired
134 // parameter is not found or is not an AlarmTimerAction, an empty value is
135 // returned.
136 COMPONENT_EXPORT(ASSISTANT_UTIL)
137 base::Optional<AlarmTimerAction> GetDeepLinkParamAsAlarmTimerAction(
138     const std::map<std::string, std::string>& params);
139 
140 // Returns a specific bool |param| from the given parameters. If the desired
141 // parameter is not found or is not a bool, an empty value is returned.
142 COMPONENT_EXPORT(ASSISTANT_UTIL)
143 base::Optional<bool> GetDeepLinkParamAsBool(
144     const std::map<std::string, std::string>& params,
145     DeepLinkParam param);
146 
147 // Returns a specific entry point |param| from the given parameters. If the
148 // desired parameter is not found or is not mappable to an Assistant entry
149 // point, an empty value is returned.
150 COMPONENT_EXPORT(ASSISTANT_UTIL)
151 base::Optional<chromeos::assistant::AssistantEntryPoint>
152 GetDeepLinkParamAsEntryPoint(const std::map<std::string, std::string>& params,
153                              DeepLinkParam param);
154 
155 // Returns a specific GURL |param| from the given parameters. If the desired
156 // parameter is not found, an absent value is returned.
157 COMPONENT_EXPORT(ASSISTANT_UTIL)
158 base::Optional<GURL> GetDeepLinkParamAsGURL(
159     const std::map<std::string, std::string>& params,
160     DeepLinkParam param);
161 
162 // Returns a specific int |param| from the given parameters. If the desired
163 // parameter is not found or is not an int, an empty value is returned.
164 COMPONENT_EXPORT(ASSISTANT_UTIL)
165 base::Optional<int32_t> GetDeepLinkParamAsInt(
166     const std::map<std::string, std::string>& params,
167     DeepLinkParam param);
168 
169 // Returns a specific int64 |param| from the given parameters. If the desired
170 // parameter is not found or is not an int64, an empty value is returned.
171 COMPONENT_EXPORT(ASSISTANT_UTIL)
172 base::Optional<int64_t> GetDeepLinkParamAsInt64(
173     const std::map<std::string, std::string>& params,
174     DeepLinkParam param);
175 
176 // Returns a specific ProactiveSuggestionsAction |param| from the given
177 // parameters. If the desired parameter is not found, an empty value is
178 // returned.
179 COMPONENT_EXPORT(ASSISTANT_UTIL)
180 base::Optional<ProactiveSuggestionsAction>
181 GetDeepLinkParamAsProactiveSuggestionsAction(
182     const std::map<std::string, std::string>& params,
183     DeepLinkParam param);
184 
185 // Returns a specific query source |param| from the given parameters. If the
186 // desired parameter is not found or is not mappable to an Assistant query
187 // source, an empty value is returned.
188 COMPONENT_EXPORT(ASSISTANT_UTIL)
189 base::Optional<chromeos::assistant::AssistantQuerySource>
190 GetDeepLinkParamAsQuerySource(const std::map<std::string, std::string>& params,
191                               DeepLinkParam param);
192 
193 // Returns a specific ReminderAction |param| from the given parameters. If the
194 // desired parameter is not found, an empty value is returned.
195 COMPONENT_EXPORT(ASSISTANT_UTIL)
196 base::Optional<ReminderAction> GetDeepLinkParamAsRemindersAction(
197     const std::map<std::string, std::string> params,
198     DeepLinkParam param);
199 
200 // Returns TimeDelta from the given parameters. If the desired parameter is not
201 // found, can't convert to TimeDelta or not a time type parameter, an empty
202 // value is returned.
203 COMPONENT_EXPORT(ASSISTANT_UTIL)
204 base::Optional<base::TimeDelta> GetDeepLinkParamAsTimeDelta(
205     const std::map<std::string, std::string>& params,
206     DeepLinkParam param);
207 
208 // Returns the deep link type of the specified |url|. If the specified url is
209 // not a supported deep link, DeepLinkType::kUnsupported is returned.
210 COMPONENT_EXPORT(ASSISTANT_UTIL) DeepLinkType GetDeepLinkType(const GURL& url);
211 
212 // Returns true if the specified |url| is a deep link of the given |type|.
213 COMPONENT_EXPORT(ASSISTANT_UTIL)
214 bool IsDeepLinkType(const GURL& url, DeepLinkType type);
215 
216 // Returns true if the specified |url| is a deep link, false otherwise.
217 COMPONENT_EXPORT(ASSISTANT_UTIL) bool IsDeepLinkUrl(const GURL& url);
218 
219 // Returns the Assistant URL for the deep link of the specified |type|. A return
220 // value will only be present if the deep link type is one of {kLists, kNotes,
221 // or kReminders}. If |id| is not contained in |params|, the returned URL will
222 // be for the top-level Assistant URL. Otherwise, the URL will correspond to
223 // the resource identified by |id|.
224 COMPONENT_EXPORT(ASSISTANT_UTIL)
225 base::Optional<GURL> GetAssistantUrl(
226     DeepLinkType type,
227     const std::map<std::string, std::string>& params);
228 
229 // Returns the URL for the specified Chrome Settings |page|. If page is absent
230 // or not allowed, the URL will be for top-level Chrome Settings.
231 COMPONENT_EXPORT(ASSISTANT_UTIL)
232 GURL GetChromeSettingsUrl(const base::Optional<std::string>& page);
233 
234 // Returns the web URL for the specified |deep_link|. A return value will only
235 // be present if |deep_link| is a web deep link as identified by the
236 // IsWebDeepLink(GURL) API.
237 COMPONENT_EXPORT(ASSISTANT_UTIL)
238 base::Optional<GURL> GetWebUrl(const GURL& deep_link);
239 
240 // Returns the web URL for a deep link of the specified |type| with the given
241 // |params|. A return value will only be present if the deep link type is a web
242 // deep link type as identified by the IsWebDeepLinkType(DeepLinkType) API.
243 COMPONENT_EXPORT(ASSISTANT_UTIL)
244 base::Optional<GURL> GetWebUrl(
245     DeepLinkType type,
246     const std::map<std::string, std::string>& params);
247 
248 // Returns true if the specified |deep_link| is a web deep link.
249 COMPONENT_EXPORT(ASSISTANT_UTIL) bool IsWebDeepLink(const GURL& deep_link);
250 
251 // Returns true if the specified deep link |type| is a web deep link.
252 COMPONENT_EXPORT(ASSISTANT_UTIL)
253 bool IsWebDeepLinkType(DeepLinkType type,
254                        const std::map<std::string, std::string>& params);
255 
256 }  // namespace util
257 }  // namespace assistant
258 }  // namespace ash
259 
260 #endif  // ASH_ASSISTANT_UTIL_DEEP_LINK_UTIL_H_
261