Skip to content
This repository was archived by the owner on Apr 24, 2025. It is now read-only.

Commit 7e3e4b3

Browse files
jankoenigjankoenig
authored
🔀 Merge pull request #1638 from sadlowskij/v4/feature/alexa-start-connection-output
✨ Add StartConnectionOutput for Alexa
2 parents 4c86954 + 4138510 commit 7e3e4b3

15 files changed

+274
-334
lines changed

‎platforms/platform-alexa/docs/README.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -572,7 +572,41 @@ You can build Alexa Skills with Jovo that make use of the Alexa Conversations di
572572

573573
You can use Jovo with [Alexa Skill Connections](https://developer.amazon.com/docs/alexa/custom-skills/understand-skill-connections.html) by sending a `Connections.StartConnection` directive as shown in the [official Alexa docs](https://developer.amazon.com/docs/alexa/custom-skills/use-skill-connections-to-request-tasks.html#implement-a-handler-to-return-a-connectionsstartconnection-directive-to-use-skill-connection).
574574

575-
For this, the Jovo Alexa integration offers convenience [output classes](https://www.jovo.tech/docs/output-classes). Below is an overview of all classes:
575+
For example, if you want to connect to a [custom task in a specific skill](https://developer.amazon.com/en-US/docs/alexa/custom-skills/use-skill-connections-to-request-tasks.html#for-custom-task-direct-skill-connection-with-send_errors_only), you can use the `StartConnectionOutput` class provided by the Jovo Alexa integration.
576+
577+
```typescript
578+
import { StartConnectionOutput, OnCompletion } from '@jovotech/platform-alexa';
579+
// ...
580+
581+
someHandler() {
582+
// ...
583+
584+
return this.$send(StartConnectionOutput, {
585+
taskName: {
586+
amazonPredefinedTask: false,
587+
name: 'CountDown',
588+
},
589+
// Input for the task
590+
input: {
591+
upperLimit: 10,
592+
lowerLimit: 1,
593+
},
594+
// Decides whether session is picked up after task
595+
onCompletion: OnCompletion.SendErrorsOnly,
596+
token: '<your-token>',
597+
// defaults to 1
598+
taskVersion: 1,
599+
// This is mandatory in case taskName.amazonPredefinedTask is false
600+
providerSkillId: '<skill-id>',
601+
});
602+
}
603+
```
604+
605+
The Output Options can be changed to create a [managed skill connection](https://developer.amazon.com/en-US/docs/alexa/custom-skills/use-skill-connections-to-request-tasks.html#for-managed-skill-connection), by setting `taskName.amazonPredefinedTask` to true and omitting `providerSkillId`.
606+
607+
In case the session is supposed to be [resumed](https://developer.amazon.com/en-US/docs/alexa/custom-skills/use-skill-connections-to-request-tasks.html#return-connectionsstartconnection-directive-with-resume_session-set-explicitly-or-by-default) after the task is handled, `onCompletion` can be changed to `OnCompletion.ResumeSession`.
608+
609+
For some specific connections, the Jovo Alexa integration offers convenience [output classes](https://www.jovo.tech/docs/output-classes). Below is an overview of all classes:
576610

577611
- [`ConnectionAskForPermissionConsentOutput`](https://github.com/jovotech/jovo-framework/tree/v4/latest/platforms/platform-alexa/src/output/templates/ConnectionAskForPermissionConsentOutput.ts)
578612
- [`ConnectionLinkAppOutput`](https://github.com/jovotech/jovo-framework/tree/v4/latest/platforms/platform-alexa/src/output/templates/ConnectionLinkAppOutput.ts)

‎platforms/platform-alexa/src/output/models/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@ export * from './common/AsinProduct';
5757
export * from './common/ConnectionPostalAddress';
5858
export * from './common/ConsentLevel';
5959
export * from './common/PermissionScope';
60+
export * from './common/OnCompletion';
6061
export * from './dialog/DialogConfirmIntentDirective';
6162
export * from './dialog/DialogConfirmSlotDirective';
6263
export * from './dialog/DialogDelegateDirective';

‎platforms/platform-alexa/src/output/templates/ConnectionAddToShoppingCartOutput.ts‎

Lines changed: 10 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { BaseOutput, Output, OutputOptions, OutputTemplate } from '@jovotech/framework';
22
import { AsinProduct } from '../models';
33
import { OnCompletion } from '../models/common/OnCompletion';
4+
import { StartConnectionOutput } from './StartConnectionOutput';
45

56
export interface ConnectionAddToShoppingCartOutputOptions extends OutputOptions {
67
shouldEndSession?: boolean;
@@ -19,33 +20,15 @@ export class ConnectionAddToShoppingCartOutput extends BaseOutput<ConnectionAddT
1920
}
2021

2122
build(): OutputTemplate | OutputTemplate[] {
22-
const shouldEndSession =
23-
this.options.onCompletion === OnCompletion.SendErrorsOnly
24-
? true
25-
: this.options.shouldEndSession;
26-
27-
return {
28-
message: this.options.message,
29-
platforms: {
30-
alexa: {
31-
nativeResponse: {
32-
response: {
33-
shouldEndSession,
34-
directives: [
35-
{
36-
type: 'Connections.StartConnection',
37-
uri: 'connection://AMAZON.AddToShoppingCart/1',
38-
input: {
39-
products: this.options.products,
40-
},
41-
token: this.options.token,
42-
onCompletion: this.options.onCompletion,
43-
},
44-
],
45-
},
46-
},
47-
},
23+
return new StartConnectionOutput(this.jovo, {
24+
taskName: { name: 'AddToShoppingCart', amazonPredefinedTask: true },
25+
taskVersion: 1,
26+
shouldEndSession: this.options.shouldEndSession,
27+
onCompletion: this.options.onCompletion,
28+
input: {
29+
products: this.options.products,
4830
},
49-
};
31+
token: this.options.token,
32+
}).build();
5033
}
5134
}

‎platforms/platform-alexa/src/output/templates/ConnectionAskForPermissionConsentOutput.ts‎

Lines changed: 12 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { BaseOutput, Output, OutputOptions, OutputTemplate } from '@jovotech/framework';
22
import { ConnectionPermissionScopeLike, ConsentLevelLike } from '../models';
33
import { OnCompletion } from '../models/common/OnCompletion';
4+
import { StartConnectionOutput } from './StartConnectionOutput';
45

56
export interface PermissionScopeItem {
67
permissionScope: ConnectionPermissionScopeLike;
@@ -24,35 +25,18 @@ export class ConnectionAskForPermissionConsentOutput extends BaseOutput<Connecti
2425
}
2526

2627
build(): OutputTemplate | OutputTemplate[] {
27-
const shouldEndSession =
28-
this.options.onCompletion === OnCompletion.SendErrorsOnly
29-
? true
30-
: this.options.shouldEndSession;
28+
return new StartConnectionOutput(this.jovo, {
29+
taskName: { name: 'AskForPermissionsConsent', amazonPredefinedTask: true },
30+
taskVersion: 2,
3131

32-
return {
33-
message: this.options.message,
34-
platforms: {
35-
alexa: {
36-
nativeResponse: {
37-
response: {
38-
shouldEndSession,
39-
directives: [
40-
{
41-
type: 'Connections.StartConnection',
42-
uri: 'connection://AMAZON.AskForPermissionsConsent/2',
43-
input: {
44-
'@type': 'AskForPermissionsConsentRequest',
45-
'@version': '2',
46-
'permissionScopes': this.options.permissionScopes,
47-
},
48-
token: this.options.token,
49-
onCompletion: this.options.onCompletion,
50-
},
51-
],
52-
},
53-
},
54-
},
32+
shouldEndSession: this.options.shouldEndSession,
33+
onCompletion: this.options.onCompletion,
34+
input: {
35+
'@type': 'AskForPermissionsConsentRequest',
36+
'@version': '2',
37+
'permissionScopes': this.options.permissionScopes,
5538
},
56-
};
39+
token: this.options.token,
40+
}).build();
5741
}
5842
}

‎platforms/platform-alexa/src/output/templates/ConnectionBuyShoppingProductsOutput.ts‎

Lines changed: 10 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { BaseOutput, Output, OutputOptions, OutputTemplate } from '@jovotech/framework';
22
import { AsinProduct } from '../models';
33
import { OnCompletion } from '../models/common/OnCompletion';
4+
import { StartConnectionOutput } from './StartConnectionOutput';
45

56
export interface ConnectionBuyShoppingProductsOutputOptions extends OutputOptions {
67
shouldEndSession?: boolean;
@@ -19,33 +20,15 @@ export class ConnectionBuyShoppingProductsOutput extends BaseOutput<ConnectionBu
1920
}
2021

2122
build(): OutputTemplate | OutputTemplate[] {
22-
const shouldEndSession =
23-
this.options.onCompletion === OnCompletion.SendErrorsOnly
24-
? true
25-
: this.options.shouldEndSession;
26-
27-
return {
28-
message: this.options.message,
29-
platforms: {
30-
alexa: {
31-
nativeResponse: {
32-
response: {
33-
shouldEndSession,
34-
directives: [
35-
{
36-
type: 'Connections.StartConnection',
37-
uri: 'connection://AMAZON.BuyShoppingProducts/1',
38-
input: {
39-
products: this.options.products,
40-
},
41-
token: this.options.token,
42-
onCompletion: this.options.onCompletion,
43-
},
44-
],
45-
},
46-
},
47-
},
23+
return new StartConnectionOutput(this.jovo, {
24+
taskName: { name: 'BuyShoppingProducts', amazonPredefinedTask: true },
25+
taskVersion: 1,
26+
shouldEndSession: this.options.shouldEndSession,
27+
onCompletion: this.options.onCompletion,
28+
input: {
29+
products: this.options.products,
4830
},
49-
};
31+
token: this.options.token,
32+
}).build();
5033
}
5134
}

‎platforms/platform-alexa/src/output/templates/ConnectionLinkAppOutput.ts‎

Lines changed: 21 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { BaseOutput, Output, OutputOptions, OutputTemplate } from '@jovotech/framework';
22
import { OnCompletion } from '../models/common/OnCompletion';
3+
import { StartConnectionOutput } from './StartConnectionOutput';
34

45
export enum DirectLaunchDefaultPromptBehavior {
56
Speak = 'SPEAK',
@@ -30,44 +31,27 @@ export class ConnectionLinkAppOutput extends BaseOutput<ConnectionLinkAppOutputO
3031
}
3132

3233
build(): OutputTemplate | OutputTemplate[] {
33-
const shouldEndSession =
34-
this.options.onCompletion === OnCompletion.SendErrorsOnly
35-
? true
36-
: this.options.shouldEndSession;
37-
38-
return {
39-
message: this.options.message,
40-
platforms: {
41-
alexa: {
42-
nativeResponse: {
43-
response: {
44-
shouldEndSession,
45-
directives: [
46-
{
47-
type: 'Connections.StartConnection',
48-
uri: 'connection://AMAZON.LinkApp/2',
49-
input: {
50-
links: this.options.links,
51-
prompt: {
52-
topic: this.options.topic,
53-
directLaunchDefaultPromptBehavior:
54-
this.options.directLaunchDefaultPromptBehavior,
55-
},
56-
directLaunch: {
57-
enabled: this.options.directLaunchEnabled,
58-
},
59-
sendToDevice: {
60-
enabled: this.options.sendToDeviceEnabled,
61-
},
62-
},
63-
token: this.options.token,
64-
onCompletion: this.options.onCompletion,
65-
},
66-
],
67-
},
68-
},
34+
return new StartConnectionOutput(this.jovo, {
35+
taskName: {
36+
name: 'LinkApp',
37+
},
38+
taskVersion: 2,
39+
shouldEndSession: this.options.shouldEndSession,
40+
onCompletion: this.options.onCompletion,
41+
input: {
42+
links: this.options.links,
43+
prompt: {
44+
topic: this.options.topic,
45+
directLaunchDefaultPromptBehavior: this.options.directLaunchDefaultPromptBehavior,
46+
},
47+
directLaunch: {
48+
enabled: this.options.directLaunchEnabled,
49+
},
50+
sendToDevice: {
51+
enabled: this.options.sendToDeviceEnabled,
6952
},
7053
},
71-
};
54+
token: this.options.token,
55+
}).build();
7256
}
7357
}

‎platforms/platform-alexa/src/output/templates/ConnectionPrintImageOutput.ts‎

Lines changed: 15 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { BaseOutput, Output, OutputOptions, OutputTemplate } from '@jovotech/framework';
22
import { OnCompletion } from '../models/common/OnCompletion';
3+
import { StartConnectionOutput } from './StartConnectionOutput';
34

45
export enum ImageType {
56
Jpg = 'JPG',
@@ -28,38 +29,20 @@ export class ConnectionPrintImageOutput extends BaseOutput<ConnectionPrintImageO
2829
}
2930

3031
build(): OutputTemplate | OutputTemplate[] {
31-
const shouldEndSession =
32-
this.options.onCompletion === OnCompletion.SendErrorsOnly
33-
? true
34-
: this.options.shouldEndSession;
35-
36-
return {
37-
message: this.options.message,
38-
platforms: {
39-
alexa: {
40-
nativeResponse: {
41-
response: {
42-
shouldEndSession,
43-
directives: [
44-
{
45-
type: 'Connections.StartConnection',
46-
uri: 'connection://AMAZON.PrintImage/1',
47-
input: {
48-
'@type': 'PrintImageRequest',
49-
'@version': '1',
50-
'title': this.options.title,
51-
'description': this.options.description,
52-
'url': this.options.url,
53-
'imageType': this.options.imageType,
54-
},
55-
token: this.options.token,
56-
onCompletion: this.options.onCompletion,
57-
},
58-
],
59-
},
60-
},
61-
},
32+
return new StartConnectionOutput(this.jovo, {
33+
taskName: { name: 'PrintImage', amazonPredefinedTask: true },
34+
taskVersion: 1,
35+
shouldEndSession: this.options.shouldEndSession,
36+
onCompletion: this.options.onCompletion,
37+
input: {
38+
'@type': 'PrintImageRequest',
39+
'@version': '1',
40+
'title': this.options.title,
41+
'description': this.options.description,
42+
'url': this.options.url,
43+
'imageType': this.options.imageType,
6244
},
63-
};
45+
token: this.options.token,
46+
}).build();
6447
}
6548
}

‎platforms/platform-alexa/src/output/templates/ConnectionPrintPdfOutput.ts‎

Lines changed: 14 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { BaseOutput, Output, OutputOptions, OutputTemplate } from '@jovotech/framework';
22
import { OnCompletion } from '../models/common/OnCompletion';
3+
import { StartConnectionOutput } from './StartConnectionOutput';
34

45
export interface ConnectionPrintPdfOutputOptions extends OutputOptions {
56
shouldEndSession?: boolean;
@@ -21,37 +22,19 @@ export class ConnectionPrintPdfOutput extends BaseOutput<ConnectionPrintPdfOutpu
2122
}
2223

2324
build(): OutputTemplate | OutputTemplate[] {
24-
const shouldEndSession =
25-
this.options.onCompletion === OnCompletion.SendErrorsOnly
26-
? true
27-
: this.options.shouldEndSession;
28-
29-
return {
30-
message: this.options.message,
31-
platforms: {
32-
alexa: {
33-
nativeResponse: {
34-
response: {
35-
shouldEndSession,
36-
directives: [
37-
{
38-
type: 'Connections.StartConnection',
39-
uri: 'connection://AMAZON.PrintPDF/1',
40-
input: {
41-
'@type': 'PrintPDFRequest',
42-
'@version': '1',
43-
'title': this.options.title,
44-
'description': this.options.description,
45-
'url': this.options.url,
46-
},
47-
token: this.options.token,
48-
onCompletion: this.options.onCompletion,
49-
},
50-
],
51-
},
52-
},
53-
},
25+
return new StartConnectionOutput(this.jovo, {
26+
taskName: { name: 'PrintPDF', amazonPredefinedTask: true },
27+
taskVersion: 1,
28+
shouldEndSession: this.options.shouldEndSession,
29+
onCompletion: this.options.onCompletion,
30+
input: {
31+
'@type': 'PrintPDFRequest',
32+
'@version': '1',
33+
'title': this.options.title,
34+
'description': this.options.description,
35+
'url': this.options.url,
5436
},
55-
};
37+
token: this.options.token,
38+
}).build();
5639
}
5740
}

0 commit comments

Comments
 (0)