The Bixby viv.shareVia
library capsule allows your capsule to send content to other applications, using Android intents. The library provides access to the Android share menu, which lets the user choose a target application to send the shared data to and returns a target name to your capsule.
A sample capsule that demonstrates viv.shareVia
is available as library-share-via-example in the Bixby Capsule Samples Collection on GitHub.
Video Tutorial: ShareVia Library - How to Share Stuff in Your Capsule
Types are always in the viv.*
namespace, and in the viv.shareVia.*
namespace unless another namespace is specified (e.g., viv.rating.*
). All properties have a cardinality of min (Required)
, max (One)
unless otherwise specified.
The AppInfo
concept contains sharing target activity information. This can be used by your capsule to determine both the application to send data to and the specific data to send.
Property | Type | Kind | Notes |
---|---|---|---|
packageName | PackageName | text | application package name |
activityName | ActivityName | text | activity class name |
activityLabel | ActivityLabel | text | |
appLabel | AppLabel | text | application name |
iconUrl | IconUrl | text | Optional |
This structure contains metadata about whether an application was successfully selected for sharing via the share screen.
Property | Type | Kind | Notes |
---|---|---|---|
appInfo | AppInfo | structure | only set on success |
selectAppResultType | SelectAppResultType | name | (1) |
selectAppResultDescription | SelectAppResultDescription | name | (2) |
result_type_success
, when an application to share with has been selected, or result_type_fail
, in all other cases.result_desc_matched
: an application has been selected and the appInfo
field has been populated. This will be the value if the result type is result_type_success
.result_desc_not_matched
: Bixby could not find an application to share data with.result_desc_matched_more_than_one
: more than one possible application to share with was returned.result_desc_not_exist_search_query
: the SearchQuery
field was empty.This concept is sent to your capsule's action endpoint along with SelectAppResult
.
Property | Type | Kind | Notes |
---|---|---|---|
intentType | IntentType | text | |
intentAction | IntentAction | text | |
intentExtraInfos | IntentExtraInfo | structure | Optional, Many |
One or more of these structures can optionally be included in IntentInfo
to pass data in the form of key/value pairs.
Property | Type | Kind | Notes |
---|---|---|---|
extraName | ExtraName | text | |
extraValue | ExtraValue | text |
This primitive name
concept is used for training purposes.
The Sharing capsule does not send the shared contents to the target application; your capsule must implement its own function, accepting IntentInfo
and SelectAppResult
concepts as inputs.
Your application should implement an action that outputs an IntentInfo
concept. One way to do this is to extend IntentInfo
and implement a FindIntentInfo
action:
structure (IntentInfo) {
extends (shareVia.IntentInfo)
}
action (FindIntentInfo) {
type (Constructor)
collect {
// ... inputs from your capsule ...
}
output (IntentInfo)
}
Your actions might also create IntentInfo
as a computed-input
.
The shareVia.SearchQuery
primitive concept is provided for training purposes, to allow your capsule to respond to utterances such as "share via Facebook":
[g:viv.yourcapsule.shareVia] Share via (Facebook)[v:viv.shareVia.SearchQuery]
There are no actions in viv.shareVia
that implement searching on SearchQuery
; if you use it as an input for FindIntentInfo
(or your capsule's equivalent), you must provide an appropriate domain-specific implementation.
The final step of implementing sharing is to add a client endpoint for the sharing action itself. In your endpoints.bxb
file, add an action-endpoint
block that will receive the IntentInfo
and SelectAppResult
concepts:
action-endpoint (ShareVia) {
accepted-inputs (intentInfo, selectAppResult)
client-endpoint {
input-mapper (capsuleInputMapper.js)
}
}
Your capsuleInputMapper.js
file should pass the appropriate data to the application specified in the appInfo
property of selectAppResult
. This can be done by returning an application-specific URI:
// defined by the client application's intent filter; see
// https://developer.android.com/training/app-links/deep-linking
const scheme = "intent";
const host = "com.sec.android.your_app";
module.exports.shareContents = function (intentInfo, selectappResult) {
var uriType = "punchOut";
var actionId = "share_action";
var resultType = SelectAppResult.selectAppResultType;
var resultDescription = SelectAppResult.selectAppResultDescription;
var params = "?package=" + selectAppResult.appInfo.packageName;
var uri;
if (resultType == "result_type_success") {
params += "&activity=" + selectAppResult.appInfo.activityName;
}
else {
params += "&error=" + resultDescription;
}
uri = scheme + "://" + host + "/" + actionId + "/" +_ uriType + params;
return {
uri: uri
}
}
The URI returned is defined entirely by your application. This example uses intent
as the scheme, but that is an arbitrary value. See Create Deep Links to App Content in Android's documentation.