From 014801cdeeb5f4b1e01153f283d079177a919cb1 Mon Sep 17 00:00:00 2001 From: "murat.bahar@gmail.com" Date: Tue, 24 Apr 2018 17:26:44 -0700 Subject: [PATCH 1/3] docs --- docs/amplify-theme/_sass/_variables.scss | 4 +- docs/media/api_guide.md | 4 +- docs/media/authentication_guide.md | 5 +- .../react-native-access-apis.rst.md | 126 ++++++++ .../react-native-access-databases.rst.md | 294 ++++++++++++++++++ .../react-native-add-analytics.rst.md | 104 +++++++ .../react-native-add-storage.rst.md | 115 +++++++ .../react-native-add-user-sign-in.rst.md | 61 ++++ .../react-native-aws-mobile-reference.rst.md | 9 + .../react-native-getting-started.rst.md | 143 +++++++++ .../react-native-host-frontend.rst.md | 39 +++ .../getting-started/web-access-apis.rst.md | 174 +++++++++++ .../web-access-databases.rst.md | 211 +++++++++++++ .../getting-started/web-add-analytics.rst.md | 101 ++++++ .../getting-started/web-add-storage.rst.md | 120 +++++++ .../web-add-user-sign-in.rst.md | 59 ++++ .../web-aws-mobile-reference.rst.md | 5 + .../web-getting-started.rst.md | 199 ++++++++++++ .../getting-started/web-host-frontend.rst.md | 69 ++++ 19 files changed, 1837 insertions(+), 5 deletions(-) create mode 100644 docs/media/getting-started/react-native-access-apis.rst.md create mode 100644 docs/media/getting-started/react-native-access-databases.rst.md create mode 100644 docs/media/getting-started/react-native-add-analytics.rst.md create mode 100644 docs/media/getting-started/react-native-add-storage.rst.md create mode 100644 docs/media/getting-started/react-native-add-user-sign-in.rst.md create mode 100644 docs/media/getting-started/react-native-aws-mobile-reference.rst.md create mode 100644 docs/media/getting-started/react-native-getting-started.rst.md create mode 100644 docs/media/getting-started/react-native-host-frontend.rst.md create mode 100644 docs/media/getting-started/web-access-apis.rst.md create mode 100644 docs/media/getting-started/web-access-databases.rst.md create mode 100644 docs/media/getting-started/web-add-analytics.rst.md create mode 100644 docs/media/getting-started/web-add-storage.rst.md create mode 100644 docs/media/getting-started/web-add-user-sign-in.rst.md create mode 100644 docs/media/getting-started/web-aws-mobile-reference.rst.md create mode 100644 docs/media/getting-started/web-getting-started.rst.md create mode 100644 docs/media/getting-started/web-host-frontend.rst.md diff --git a/docs/amplify-theme/_sass/_variables.scss b/docs/amplify-theme/_sass/_variables.scss index 0afa4488885..32571238a3a 100755 --- a/docs/amplify-theme/_sass/_variables.scss +++ b/docs/amplify-theme/_sass/_variables.scss @@ -50,8 +50,8 @@ $color-theme-red: #FFECE6 !default; $color-theme-yellow: #FCFDE8 !default; /* ----- Font families ----- */ -$font-family-primary: '"Amazon Ember",Arial,sans-serif', sans-serif !default; -$font-family-secondary: '"Amazon Ember",Arial,sans-serif', sans-serif !default; +$font-family-primary: 'Amazon Ember,Arial,sans-serif', sans-serif !default; +$font-family-secondary: 'Amazon Ember,Arial,sans-serif', sans-serif !default; $font-family-monospace: 'Source Code Pro', monospace !default; /* ----- Font sizes ----- */ diff --git a/docs/media/api_guide.md b/docs/media/api_guide.md index 6fb51ee4901..17ac9f22036 100644 --- a/docs/media/api_guide.md +++ b/docs/media/api_guide.md @@ -444,7 +444,7 @@ const GetEvent = `query GetEvent($id: ID! $nextToken: String) { }`; // Simple query -const allEvents = await API.graphql({ ListEvents }); +const allEvents = await API.graphql(graphqlOperation(ListEvents)); // Query using a parameter const oneEvent = await API.graphql(graphqlOperation(GetEvent, { id: 'some id' })); @@ -474,7 +474,7 @@ const eventDetails = { name: 'Party tonight!', when: '8:00pm', where: 'Ballroom', - decription: 'Coming together as a team!' + description: 'Coming together as a team!' }; const newEvent = await API.graphql(graphqlOperation(CreateEvent, eventDetails)); diff --git a/docs/media/authentication_guide.md b/docs/media/authentication_guide.md index fbaf0392a38..8921f39bd25 100644 --- a/docs/media/authentication_guide.md +++ b/docs/media/authentication_guide.md @@ -83,7 +83,10 @@ Auth.signIn(username, password) .then(user => console.log(user)) .catch(err => console.log(err)); -// If MFA enabled, keep the user object from sign in, collect confirmation code, and then +// If MFA is enabled, confirm user signing +// `user` : Return object from Auth.signIn() +// `code` : Confirmation code +// `mfaType` : MFA Type e.g. SMS, TOTP. Auth.confirmSignIn(user, code, mfaType) .then(data => console.log(data)) .catch(err => console.log(err)); diff --git a/docs/media/getting-started/react-native-access-apis.rst.md b/docs/media/getting-started/react-native-access-apis.rst.md new file mode 100644 index 00000000000..959fb01ba98 --- /dev/null +++ b/docs/media/getting-started/react-native-access-apis.rst.md @@ -0,0 +1,126 @@ +Access Your APIs +================ + +Set Up Your Backend +------------------- + +The AWS Mobile Cloud Logic <cloud-logic> feature lets you call +APIs in the cloud. API calls are handled by your serverless Lambda +functions. + +**To enable cloud APIs in your app** + +``` {.sourceCode .bash} +awsmobile cloud-api enable + +awsmobile push +``` + +Enabling Cloud Logic in your app adds a sample API, +`sampleCloudApi`{.sourceCode} to your project that can be used for +testing. + +You can find the sample handler function for the API by running +`awsmobile console`{.sourceCode} in your app root folder, and then +choosing the Cloud Logic feature in your project. + +![View your sample cloud API and its lambda function handler.](images/web-view-cloud-api.png) + +### Quickly Test Your API From the CLI + +The `sampleCloudApi`{.sourceCode} and its handler function allow you to +make end to end API calls. + +**To test invocation of your unsigned APIs in the development +environment** + +``` {.sourceCode .bash} +awsmobile cloud-api invoke [init] +``` + +For the `sampleCloudApi`{.sourceCode} you may use the following examples +to test the `post`{.sourceCode} method + +``` {.sourceCode .bash} +awsmobile cloud-api invoke sampleCloudApi post /items '{"body": {"testKey":"testValue"}}' +``` + +This call will return a response similar to the following. + +``` {.sourceCode .bash} +{ success: 'post call succeed!', +url: '/items', +body: { testKey: 'testValue' } } +``` + +**To test the :get method** + +``` {.sourceCode .bash} +awsmobile cloud-api invoke sampleCloudApi get /items +``` + +This will return a response as follows. + +``` {.sourceCode .bash} +{ success: 'get call succeed!', url: '/items' } +``` + +Connect to Your Backend +----------------------- + +Once you have created your own Cloud Logic <cloud-logic> APIs and +Lambda functions, you can call them from your app. + +**To call APIs from your app** + +In App.js (or other code that runs at launch-time), add the following +import. + +``` {.sourceCode .java} +import Amplify, { API } from 'aws-amplify'; +import aws_exports from './aws-exports'; +Amplify.configure(aws_exports); +``` + +Then add this to the component that calls your API. + +``` {.sourceCode .java} +state = { apiResponse: null }; + +async getSample() { + const path = "/items"; // you can specify the path + const apiResponse = await API.get("sampleCloudApi" , path); //replace the API name + console.log('response:' + apiResponse); + this.setState({ apiResponse }); +} +``` + +To invoke your API from a UI element, add an API call from within your +component's `render()`{.sourceCode} method. + +``` {.sourceCode .html} + + + ``` + +Open your app locally and test out guessing the number by running +`awsmobile run`{.sourceCode}. + +Your entire component should look like the following: + +### Next Steps + +- Learn how to retrieve specific items and more with the [API module + in AWS + Amplify](https://aws.github.io/aws-amplify/media/developer_guide.html). +- Learn how to enable more features for your app with the [AWS Mobile + CLI](https://aws.github.io/aws-amplify). +- Learn more about what happens behind the scenes, see [Set up Lambda + and API + Gateway](https://alpha-docs-aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html). + diff --git a/docs/media/getting-started/web-access-databases.rst.md b/docs/media/getting-started/web-access-databases.rst.md new file mode 100644 index 00000000000..2a2a756af36 --- /dev/null +++ b/docs/media/getting-started/web-access-databases.rst.md @@ -0,0 +1,211 @@ +Access Your Database +==================== + +The AWS Mobile CLI and Amplify library make it easy to perform create, +read, update, and delete ("CRUD") actions against data stored in the +cloud through simple API calls in your JavaScript app. + +Set Up Your Backend +------------------- + +**To create a database** + +1. Enable the NoSQL database feature and configure your table. + + In the root folder of your app, run: + + ``` {.sourceCode .bash} + awsmobile database enable --prompt + ``` + +2. Choose `Open`{.sourceCode} to make the data in this table viewable + by all users of your application. + + ``` {.sourceCode .bash} + ? Should the data of this table be open or restricted by user? + ❯ Open + Restricted + ``` + +3. For this example type in todos as your `Table name`{.sourceCode}. + + ``` {.sourceCode .bash} + ? Table name: todos + ``` + +### Add columns and queries + +You are creating a table in a [NoSQL +database](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SQLtoNoSQL.html) +and adding an initial set of columns, each of which has a name and a +data type. NoSQL lets you add a column any time you store data that +contains a new column. NoSQL tables must have one column defined as the +Primary Key, which is a unique identifier for each row. + +1. For this example, follow the prompts to add three columns: team + (string), todoId (number), and text (string). + + ``` {.sourceCode .bash} + ? What would you like to name this column: team + ? Choose the data type: string + ``` + +2. When prompted to `? Add another column`{.sourceCode}, type Y and + then choose enter. Repeat the steps to create todoId and text + columns. +3. Select `team`{.sourceCode} as the primary key. + + ``` {.sourceCode .bash} + ? Select primary key + ❯ team + todoId + text + ``` + +4. Choose `(todoId)`{.sourceCode} as the sort key and then + `no`{.sourceCode} to adding any more indexes, to keep the example + simple. + + ``` {.sourceCode .bash} + ? Select sort key + ❯ todoId + text + (No Sort Key) + + ? Add index (Y/n): n + Table todos saved. + ``` + + The `todos`{.sourceCode} table is now created. + +### Use a cloud API to do CRUD operations + +To access your NoSQL database, you will create an API that can be called +from your app to perform CRUD operations. + +**To create a CRUD API** + +1. Enable and configure the Cloud Logic feature\*\* + + ``` {.sourceCode .bash} + awsmobile cloud-api enable --prompt + ``` + +2. Choose + `Create CRUD API for an existing Amazon DynamoDB table`{.sourceCode} + API for an exisitng Amazon DynamoDB table" and then choose enter. + + ``` {.sourceCode .bash} + ? Select from one of the choices below. (Use arrow keys) + Create a new API + ❯ Create CRUD API for an existing Amazon DynamoDB table + ``` + +3. Select the `todos`{.sourceCode} table created in the previous steps, + and choose enter. + + ``` {.sourceCode .bash} + ? Select Amazon DynamoDB table to connect to a CRUD API + ❯ todos + ``` + +4. Push your configuration to the cloud. Without this step, the + configuration for your database and API is now in place only on your + local machine. + + ``` {.sourceCode .bash} + awsmobile push + ``` + + The required DynamoDB tables, API Gateway endpoints, and Lambda + functions will now be created. + +### Create your first Todo + +The AWS Mobile CLI enables you to test your API from the command line. + +Run the following command to create your first todo. + +``` {.sourceCode .bash} +awsmobile cloud-api invoke todosCRUD POST /todos '{"body": {"team": "React", "todoId": 1, "text": "Learn more Amplify"}}' +``` + +Connect to Your Backend +----------------------- + +The examples in this section show how you would integrate AWS Amplify +library calls using React (see the [AWS Amplify +documentation](https://aws.github.io/aws-amplify/) to use other flavors +of Javascript). + +The following component is a simple Todo list that you might add to a +`create-react-app`{.sourceCode} project. The Todos component currently +adds and displays `todos`{.sourceCode} to and from an in memory array. + +### Displaying todos from the cloud + +The `API`{.sourceCode} module from AWS Amplify allows you connect to +DynamoDB through endpoints. + +**To retrieve and display items in a database** + +1. Import the `API`{.sourceCode} module from `aws-amplify`{.sourceCode} + at the top of the Todos component file. + + ``` {.sourceCode .javascript} + import { API } from 'aws-amplify'; + ``` + +2. Add the following `componentDidMount`{.sourceCode} to the + `Todos`{.sourceCode} component to fetch all of the + `todos`{.sourceCode}. + + ``` {.sourceCode .javascript} + async componentDidMount() { + let todos = await API.get('todosCRUD', `/todos/${this.state.team}`); + this.setState({ todos }); + } + ``` + +When the `Todos`{.sourceCode} component mounts it will fetch all of the +`todos`{.sourceCode} stored in your database and display them. + +### Saving todos to the cloud + +The following fragment shows the `saveTodo`{.sourceCode} function for +the Todo app. + +``` {.sourceCode .javascript} +async saveTodo(event) { + event.preventDefault(); + + const { team, todos } = this.state; + const todoId = todos.length + 1; + const text = this.refs.newTodo.value; + + const newTodo = {team, todoId, text}; + await API.post('todosCRUD', '/todos', { body: newTodo }); + todos.push(newTodo); + this.refs.newTodo.value = ''; + this.setState({ todos, team }); +} +``` + +Update the `form`{.sourceCode} element in the component's render +function to invoke the `saveTodo`{.sourceCode} function when the form is +submitted. + +``` {.sourceCode .javascript} +
+``` + +Your entire component should look like the following: + +#### Next Steps + +- Learn how to retrieve specific items and more with the [API module + in AWS + Amplify](https://aws.github.io/aws-amplify/media/developer_guide.html). +- Learn how to enable more features for your app with the [AWS Mobile + CLI](https://aws.github.io/aws-amplify). + diff --git a/docs/media/getting-started/web-add-analytics.rst.md b/docs/media/getting-started/web-add-analytics.rst.md new file mode 100644 index 00000000000..c3431a4109f --- /dev/null +++ b/docs/media/getting-started/web-add-analytics.rst.md @@ -0,0 +1,101 @@ +Add Analytics +============= + +Basic Analytics Backend is Enabled for Your App +----------------------------------------------- + +When you complete the AWS Mobile CLI setup and launch your app, +anonymized session and device demographics data flows to the AWS +analytics backend. + +**To send basic app usage analytics to AWS** + +Launch your app locally by running: + +``` {.sourceCode .bash} +npm start +``` + +When you use your app the [Amazon +Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/) +service gathers and visualizes analytics data. + +**To view the analytics using the Amazon Pinpoint console** + +1. Run `npm start`{.sourceCode}, `awsmobile run`{.sourceCode}, or + `awsmobile publish --test`{.sourceCode} at least once. +2. Open your project in the [AWS Mobile Hub + console](https://console.aws.amazon.com/mobilehub/). + + ``` {.sourceCode .bash} + awsmobile console + ``` + +3. Choose the Analytics icon on the left, to navigate to your project + in the [Amazon Pinpoint + console](https://console.aws.amazon.com/pinpoint/). +4. Choose Analytics on the left. + +You should see an up-tick in several graphs. + +Add Custom Analytics to Your App +-------------------------------- + +You can configure your app so that [Amazon +Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/) +gathers data for custom events that you register within the flow of your +code. + +**To instrument custom analytics in your app** + +In the file containing the event you want to track, add the following +import: + +``` {.sourceCode .java} +import { Analytics } from 'aws-amplify'; +``` + +Add the a call like the following to the spot in your JavaScript where +the tracked event should be fired: + +``` {.sourceCode .javascript} +componentDidMount() { + Analytics.record('FIRST-EVENT-NAME'); +} +``` + +Or to relevant page elements: + +``` {.sourceCode .html} +handleClick = () => { + Analytics.record('SECOND-EVENT-NAME'); +} + + +``` + +To test: + +1. Save the changes and run `npm start`{.sourceCode}, + `awsmobile run`{.sourceCode}, or + `awsmobile publish --test`{.sourceCode} to launch your app. Use your + app so that tracked events are triggered. +2. In the [Amazon Pinpoint + console](https://console.aws.amazon.com/pinpoint/), choose Events + near the top. +3. Select an event in the Event dropdown menu on the left. + +Custom event data may take a few minutes to become visible in the +console. + +Next Steps +---------- + +Learn more about the analytics in AWS Mobile which are part of the +Messaging and Analytics <messaging-and-analytics> feature. This +feature uses [Amazon +Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/welcome.html). + +Learn about AWS Mobile CLI <aws-mobile-cli-reference>. + +Learn about [AWS Mobile Amplify](https://aws.github.io/aws-amplify). diff --git a/docs/media/getting-started/web-add-storage.rst.md b/docs/media/getting-started/web-add-storage.rst.md new file mode 100644 index 00000000000..ccee07c2a6d --- /dev/null +++ b/docs/media/getting-started/web-add-storage.rst.md @@ -0,0 +1,120 @@ +Add Storage +=========== + +The AWS Mobile CLI and AWS Amplify library make it easy to store and +manage files in the cloud from your JavaScript app. + +Set Up the Backend +------------------ + +Enable the User File Storage feature by running the following commands +in the root folder of your app. + +``` {.sourceCode .bash} +awsmobile user-files enable + +awsmobile push +``` + +Connect to the Backend +---------------------- + +The examples in this section show how you would integrate AWS Amplify +library calls using React (see the [AWS Amplify +documentation](https://aws.github.io/aws-amplify) to use other flavors +of Javascript). + +The following simple component could be added to a +`create-react-app`{.sourceCode} project to present an interface that +uploads images and download them for display. + +### Upload a file + +The `Storage`{.sourceCode} module enables you to upload files to the +cloud. All uploaded files are publicly viewable by default. + +Import the `Storage`{.sourceCode} module in your component file. + +``` {.sourceCode .javascript} +// ./src/ImageViewer.js + +import { Storage } from 'aws-amplify'; +``` + +Add the following function to use the `put`{.sourceCode} function on the +`Storage`{.sourceCode} module to upload the file to the cloud, and set +your component’s state to the name of the file. + +``` {.sourceCode .javascript} +uploadFile(event) { + const file = event.target.files[0]; + const name = file.name; + + Storage.put(key, file).then(() => { + this.setState({ file: name }); + }); +} +``` + +Place a call to the `uploadFile`{.sourceCode} function in the +`input`{.sourceCode} element of the component’s render function, to +start upload when a user selects a file. + +``` {.sourceCode .javascript} +render() { + return ( +
+

Pick a file

+ +
+ ); +} +``` + +### Display an image + +To display an image, this example shows the use of the +`S3Image`{.sourceCode} component of the AWS Amplify for React library. + +1. From a terminal, run the following command in the root folder of + your app. + + ``` {.sourceCode .bash} + npm install --save aws-amplify-react + ``` + +2. Import the `S3Image`{.sourceCode} module in your component. + + ``` {.sourceCode .javascript} + import { S3Image } from 'aws-amplify-react'; + ``` + +Use the S3Image component in the render function. Update your render +function to look like the following: + +``` {.sourceCode .javascript} +render() { + return ( +
+

Pick a file

+ + { this.state && } +
+ ); +} +``` + +#### Next Steps + +- Learn how to do private file storage and more with the [Storage + module in AWS + Amplify](https://aws.github.io/aws-amplify/media/developer_guide.html). +- Learn how to enable more features for your app with the [AWS Mobile + CLI](https://aws.github.io/aws-amplify). +- Learn how to use those features in your app with the [AWS Amplify + library](https://aws.github.io/aws-amplify). +- Learn more about the [analytics for the User File Storage + feature](https://alpha-docs-aws.amazon.com/pinpoint/latest/developerguide/welcome.html). +- Learn more about how your files are stored on [Amazon Simple Storage + Service](https://aws.amazon.com/documentation/s3/). + diff --git a/docs/media/getting-started/web-add-user-sign-in.rst.md b/docs/media/getting-started/web-add-user-sign-in.rst.md new file mode 100644 index 00000000000..c4d47b082b3 --- /dev/null +++ b/docs/media/getting-started/web-add-user-sign-in.rst.md @@ -0,0 +1,59 @@ +Add Auth / User Sign-in +======================= + +Set Up Your Backend +------------------- + +The AWS Mobile CLI components for user authentication include a rich, +configurable UI for sign-up and sign-in. + +**To enable the Auth features** + +In the root folder of your app, run: + +``` {.sourceCode .java} +awsmobile user-signin enable + +awsmobile push +``` + +Connect to Your Backend +----------------------- + +The AWS Mobile CLI enables you to integrate ready-made +sign-up/sign-in/sign-out UI from the command line. + +**To add user auth UI to your app** + +1. Install AWS Amplify for React library. + + ``` {.sourceCode .bash} + npm install --save aws-amplify-react + ``` + +2. Add the following import in App.js (or other file that runs upon app + startup): + + ``` {.sourceCode .java} + import { withAuthenticator } from 'aws-amplify-react'; + ``` + +3. Then change `export default App;`{.sourceCode} to the following. + + ``` {.sourceCode .java} + export default withAuthenticator(App); + ``` + +To test, run `npm start`{.sourceCode}, `awsmobile run`{.sourceCode}, or +`awsmobile publish --test`{.sourceCode}. + +Next Steps +---------- + +Learn more about the AWS Mobile User Sign-in <user-sign-in> +feature, which uses [Amazon +Cognito](http://docs.aws.amazon.com/cognito/latest/developerguide/welcome.html). + +Learn about AWS Mobile CLI <aws-mobile-cli-reference>. + +Learn about [AWS Mobile Amplify](https://aws.github.io/aws-amplify). diff --git a/docs/media/getting-started/web-aws-mobile-reference.rst.md b/docs/media/getting-started/web-aws-mobile-reference.rst.md new file mode 100644 index 00000000000..c59919dcd0a --- /dev/null +++ b/docs/media/getting-started/web-aws-mobile-reference.rst.md @@ -0,0 +1,5 @@ +Features +======== + +The following pages contain reference material for the AWS Mobile CLI +for Web (JavaScript). diff --git a/docs/media/getting-started/web-getting-started.rst.md b/docs/media/getting-started/web-getting-started.rst.md new file mode 100644 index 00000000000..98eeaf66709 --- /dev/null +++ b/docs/media/getting-started/web-getting-started.rst.md @@ -0,0 +1,199 @@ +Get Started +=========== + +Overview +-------- + +The AWS Mobile CLI provides a command line experience that allows +frontend JavaScript developers to quickly create and integrate AWS +backend resources into their mobile apps. + +Prerequisites +------------- + +1. [Sign up for the AWS Free Tier](https://aws.amazon.com/free/). +2. Install [Node.js](https://nodejs.org/en/download/) with NPM. +3. Install AWS Mobile CLI + + ``` {.sourceCode .bash} + npm install -g awsmobile-cli + ``` + +4. Configure the CLI with your AWS credentials + + To setup permissions for the toolchain used by the CLI, run: + + ``` {.sourceCode .bash} + awsmobile configure + ``` + + If prompted for credentials, follow the steps provided by the CLI. + For more information, see + provide IAM credentials to AWS Mobile CLI <aws-mobile-cli-credentials>. + +Set Up Your Backend +------------------- + +**To configure backend features for your app** + +1. In the root folder of your app, run: + + ``` {.sourceCode .bash} + awsmobile init + ``` + + The `init`{.sourceCode} command creates a backend project for your + app. By default, analytics and web hosting are enabled in your + backend and this configuration is automatically pulled into your app + when you initialize. + +2. When prompted, provide the source directory for your project. The + CLI will generate aws-exports.js in this location. This file + contains the configuration and endpoint metadata used to link your + frontend to your backend services. + + ``` {.sourceCode .bash} + ? Where is your project's source directory: src + ``` + +3. Respond to further prompts with the following values. + + ``` {.sourceCode .bash} + ? Where is your project's distribution directory to store build artifacts: build + ? What is your project's build command: npm run-script build + ? What is your project's start command for local test run: npm run-script start + ? What awsmobile project name would you like to use: YOUR-APP-NAME-2017-11-10-15-17-48 + ``` + +After the project is created you will get a success message which also +includes details on the path where the aws-exports.js is copied. + +> ``` {.sourceCode .bash} +> awsmobile project's details logged at: awsmobilejs/#current-backend-info/backend-details.json +> awsmobile project's access information logged at: awsmobilejs/#current-backend-info/aws-exports.js +> awsmobile project's access information copied to: src/aws-exports.js +> awsmobile project's specifications logged at: awsmobilejs/#current-backend-info/mobile-hub-project.yml +> contents in #current-backend-info/ is synchronized with the latest information in the aws cloud +> ``` + +Your project is now initialized. + +
.. \_web-getting-started-configure-aws-amplify: + +Connect to Your Backend +----------------------- + +AWS Mobile uses the open source [AWS Amplify +library](https://aws.github.io/aws-amplify) to link your code to the AWS +features configured for your app. + +This section of the guide shows examples using a React application of +the kind output by `create-react-app`{.sourceCode} or a similar tool. + +**To connect the app to your configured AWS features** + +In index.js (or in other code that runs at launch-time), add the +following imports. + +``` {.sourceCode .javascript} +import Amplify from 'aws-amplify'; +import awsmobile from './YOUR-PATH-TO/aws-exports'; +``` + +Then add the following code. + +``` {.sourceCode .javascript} +Amplify.configure(awsmobile); +``` + +### Run Your App Locally + +Your app is now ready to launch and use the default features configured +by AWS Mobile. + +**To launch your app locally in a browser** + +In the root folder of your app, run: + +``` {.sourceCode .bash} +awsmobile run +``` + +Behind the scenes, this command runs `npm install`{.sourceCode} to +install the Amplify library and also pushes any backend configuration +changes to AWS Mobile. To run your app locally without pushing backend +changes you cou can choose to run `npm install`{.sourceCode} and then +run `npm start`{.sourceCode}. + +Anytime you launch your app, +app analytics are gathered and can be visualized<web-add-analytics> +in an AWS console. + +Next Steps +---------- + +### Deploy your app to the cloud + +Using a simple command, you can publish your app's frontend to hosting +on a robust content distribution network (CDN) and view it in a browser. + +**To deploy your app to the cloud and launch it in a browser** + +In the root folder of your app, run: + +``` {.sourceCode .bash} +awsmobile publish +``` + +To push any backend configuration changes to AWS and view content +locally, run `awsmobile run`{.sourceCode}. In both cases, any pending +changes you made to your backend configuration are made to your backend +resources. + +By default, the CLI configures AWS Mobile +Hosting and Streaming <hosting-and-streaming> feature, that hosts +your app on [Amazon CloudFront](https://aws.amazon.com/cloudfront/) CDN +endpoints. These locations make your app highly available to the public +on the Internet and support [media file +streaming](http://docs.aws.amazon.com/mobile-hub/latest/developerguide/url-cf-dev;Tutorials.html) + +You can also use a custom domain <web-host-frontend> for your +hosting location. + +### Test Your App on Our Mobile Devices + +Invoke a free remote test of your app on a variety of real devices and +see results, including screen shots. + +**To invoke a remote test of your app** + +In the root folder of your app, run: + +``` {.sourceCode .bash} +awsmobile publish --test +``` + +The CLI will open the reporting page for your app in the console to show +the metrics gathered from the test devices. The device that runs the +remote test you invoke resides in [AWS Device +Farm](https://aws.amazon.com/device-farm/) which provides flexible +configuration of tests and reporting. + +![image](images/web-performance-testing.png) + +### Add Features + +Add the following AWS Mobile features to your mobile app using the CLI. + +> - Analytics <web-add-analytics> +> - User Sign-in <web-add-user-sign-in> +> - NoSQL Database <web-access-databases> +> - User File Storage <web-add-storage> +> - Cloud Logic <web-access-apis> + +### Learn more + +To learn more about the commands and usage of the AWS Mobile CLI, see +the AWS Mobile CLI reference<aws-mobile-cli-reference>. + +Learn about [AWS Mobile Amplify](https://aws.github.io/aws-amplify). diff --git a/docs/media/getting-started/web-host-frontend.rst.md b/docs/media/getting-started/web-host-frontend.rst.md new file mode 100644 index 00000000000..98f0b543f22 --- /dev/null +++ b/docs/media/getting-started/web-host-frontend.rst.md @@ -0,0 +1,69 @@ +Access Your APIs +================ + +About Hosting and Streaming +--------------------------- + +The AWS Mobile Hosting and Streaming <hosting-and-streaming> +feature is especially useful to web developers. It uses the ability of +[Amazon +S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html) +buckets to statically host content and the [Amazon +CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) +content distribution network (CDN) to host on an endpoint close to every +user globally. Amazon CloudFront endpoints can also stream media +content. + +**About the Hosting and Streaming Sample App** + +When you enable Hosting and Streaming , provisions content in the root +of your source bucket which includes a local copy of the (aws-min.js). + +- aws-sdk.min.js - An source file. +- aws-config.js,- A web app configuration file that is generated to + contain constants for the endpoints for each feature you have + enabled for this project. +- index.html - Which uses a constant formed in aws-config.js to + request and display an AWS guest (unauthenticated) user identity ID + from the service. + +When you enable Hosting and Streaming an global content delivery network +(CDN) distribution is created and associated with your bucket. When +propagates the sample web app content to the bucket, the content is then +propagated to the CDN and becomes available from local endpoints around +the globe. If you configure [CloudFront +streaming](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Tutorials.html), +then media content you upload to your bucket can be streamed from those +endpoints. + +\*\* To view the Hosting and Streaming Sample App + +The Hosting and Streaming feature creates a sample JavaScript web app +that demonstrates connecting to the AWS resources of your project. + +The sample app web assets are deployed to an bucket. The bucket is +configured to host static web content for public access. + +1. In the [Mobile Hub + console](https://console.aws.amazon.com/mobilehub/home/), open your + project and then choose the Hosting and Streaming tile. +2. Choose View from S3. + + This opens a browser and displays the index.html of the sample web + app from the bucket. + + > ![Image of the |AMH| console.](images/add-aws-mobile-add-hosting-and-streaming-view-from-s3.png) + +Configure a Custom Domain for Your Web App +------------------------------------------ + +> To use your custom domain for linking to your Web app, use the service +> to configure DNS routing. +> +> For a web app hosted in a single location, see [Routing Traffic to a +> Website that Is Hosted in an Amazon S3 +> Bucket](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/RoutingToS3Bucket.html). +> +> For a web app distributed through a global CDN, see [Routing Traffic +> to an Amazon CloudFront Web Distribution by Using Your Domain +> Name](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloud-fron-distribution.html) From c9ffa7deb6be51e621f8ca2c551c1e36405be834 Mon Sep 17 00:00:00 2001 From: "murat.bahar@gmail.com" Date: Wed, 25 Apr 2018 12:21:58 -0700 Subject: [PATCH 2/3] added pages for front-end support --- docs/_config.yml | 10 +++++++--- docs/index.md | 17 +++++++---------- docs/media/ionic_guide.md | 10 ++++++++++ docs/media/react_guide.md | 4 +++- docs/media/react_native_guide.md | 4 +++- docs/media/vuejs_guide.md | 10 ++++++++++ 6 files changed, 40 insertions(+), 15 deletions(-) create mode 100644 docs/media/ionic_guide.md create mode 100644 docs/media/vuejs_guide.md diff --git a/docs/_config.yml b/docs/_config.yml index 175dd4d4127..51dc70f7a2c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -194,6 +194,10 @@ category_list: - category: Front-end Support title: Front-end Support subs: + - title: Angular + excerpt: Angular support package. + cta: Read more + url: '/media/angular_guide' - title: React excerpt: React support package. cta: Read more @@ -202,10 +206,10 @@ category_list: excerpt: React Native support package. cta: Read more url: '/media/react_native_guide' - - title: Angular - excerpt: Angular support package. + - title: Vue.js + excerpt: Vue.j support package. cta: Read more - url: '/media/angular_guide' + url: '/media/vuejs_guide' - category: CLI title: CLI subs: diff --git a/docs/index.md b/docs/index.md index d812853d00c..c439eecd52c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -17,23 +17,20 @@ marketing_grid: - title: Declarative API excerpt:

AWS Amplify provides a declarative and easy-to-use interface across different categories of cloud operations.

- See our code examples to learn how you can 'cloud-enable' your app in under 5 minutes. + See our code examples to learn how you can 'cloud-enable' your app in under 5 minutes.

- title: Bring your own frontend excerpt:

AWS Amplify goes well with any JavaScript based frontend workflow, and React Native for mobile developers.

-

See our starter kits for - React, - Ionic, - Vue, - and - React Native. - Angular is coming soon... - +

Learn more about our frontend support for + Angular, + React, + React Native, + Ionic, + Vue.js

- title: Open and Pluggable excerpt: Our default implementation works with Amazon Web Services (AWS), but AWS Amplify is designed to be open and pluggable for any custom backend or service. - # Grid navigation grid_navigation: - title: Installation diff --git a/docs/media/ionic_guide.md b/docs/media/ionic_guide.md new file mode 100644 index 00000000000..7f74625547d --- /dev/null +++ b/docs/media/ionic_guide.md @@ -0,0 +1,10 @@ +--- +--- + +# Ionic + +To help you start working with AWS Amplify, Ionic team provides a Starter App. See our [Ionic Starter App in Github](https://github.com/ionic-team/starters/tree/master/ionic-angular/official/aws). + +We will soon support Ionic components for AWS Amplify. +{: .callout .callout--info} + diff --git a/docs/media/react_guide.md b/docs/media/react_guide.md index aeb5f1c863c..196b1c6dd77 100644 --- a/docs/media/react_guide.md +++ b/docs/media/react_guide.md @@ -3,7 +3,9 @@ # React -AWS Amplify provides React Components with `aws-amplify-react` npm package. +AWS Amplify provides React Components with `aws-amplify-react` npm package. Also, to help you start working with AWS Amplify, we provide a Starter App. + +See our [React Starter App in Github](https://github.com/awslabs/aws-mobile-react-sample). ## Installation and Configuration diff --git a/docs/media/react_native_guide.md b/docs/media/react_native_guide.md index e6e2ddaad5a..c1f92116935 100644 --- a/docs/media/react_native_guide.md +++ b/docs/media/react_native_guide.md @@ -3,7 +3,9 @@ # React Native -AWS Amplify provides React Native Components with `aws-amplify-react-native` npm package. +AWS Amplify provides React Native Components with `aws-amplify-react-native` npm package. Also, to help you start working with AWS Amplify, we provide a Starter App. + +See our [React Native Starter App in Github](https://github.com/awslabs/aws-mobile-react-native-starter). ## Installation and Configuration diff --git a/docs/media/vuejs_guide.md b/docs/media/vuejs_guide.md new file mode 100644 index 00000000000..d912e21ec18 --- /dev/null +++ b/docs/media/vuejs_guide.md @@ -0,0 +1,10 @@ +--- +--- + +# Vue.js + +To help you start working with AWS Amplify, we provide a Starter App. See our [Vue.js Starter App in Github](https://github.com/aws-samples/aws-amplify-vue). + +We will soon support Vue.js components for AWS Amplify. +{: .callout .callout--info} + From 51ff8b891875f4ffea367bdcb2462384501852e3 Mon Sep 17 00:00:00 2001 From: "murat.bahar@gmail.com" Date: Wed, 25 Apr 2018 12:25:56 -0700 Subject: [PATCH 3/3] doc update --- .../react-native-access-apis.rst.md | 126 -------- .../react-native-access-databases.rst.md | 294 ------------------ .../react-native-add-analytics.rst.md | 104 ------- .../react-native-add-storage.rst.md | 115 ------- .../react-native-add-user-sign-in.rst.md | 61 ---- .../react-native-aws-mobile-reference.rst.md | 9 - .../react-native-getting-started.rst.md | 143 --------- .../react-native-host-frontend.rst.md | 39 --- .../getting-started/web-access-apis.rst.md | 174 ----------- .../web-access-databases.rst.md | 211 ------------- .../getting-started/web-add-analytics.rst.md | 101 ------ .../getting-started/web-add-storage.rst.md | 120 ------- .../web-add-user-sign-in.rst.md | 59 ---- .../web-aws-mobile-reference.rst.md | 5 - .../web-getting-started.rst.md | 199 ------------ .../getting-started/web-host-frontend.rst.md | 69 ---- 16 files changed, 1829 deletions(-) delete mode 100644 docs/media/getting-started/react-native-access-apis.rst.md delete mode 100644 docs/media/getting-started/react-native-access-databases.rst.md delete mode 100644 docs/media/getting-started/react-native-add-analytics.rst.md delete mode 100644 docs/media/getting-started/react-native-add-storage.rst.md delete mode 100644 docs/media/getting-started/react-native-add-user-sign-in.rst.md delete mode 100644 docs/media/getting-started/react-native-aws-mobile-reference.rst.md delete mode 100644 docs/media/getting-started/react-native-getting-started.rst.md delete mode 100644 docs/media/getting-started/react-native-host-frontend.rst.md delete mode 100644 docs/media/getting-started/web-access-apis.rst.md delete mode 100644 docs/media/getting-started/web-access-databases.rst.md delete mode 100644 docs/media/getting-started/web-add-analytics.rst.md delete mode 100644 docs/media/getting-started/web-add-storage.rst.md delete mode 100644 docs/media/getting-started/web-add-user-sign-in.rst.md delete mode 100644 docs/media/getting-started/web-aws-mobile-reference.rst.md delete mode 100644 docs/media/getting-started/web-getting-started.rst.md delete mode 100644 docs/media/getting-started/web-host-frontend.rst.md diff --git a/docs/media/getting-started/react-native-access-apis.rst.md b/docs/media/getting-started/react-native-access-apis.rst.md deleted file mode 100644 index 959fb01ba98..00000000000 --- a/docs/media/getting-started/react-native-access-apis.rst.md +++ /dev/null @@ -1,126 +0,0 @@ -Access Your APIs -================ - -Set Up Your Backend -------------------- - -The AWS Mobile Cloud Logic <cloud-logic> feature lets you call -APIs in the cloud. API calls are handled by your serverless Lambda -functions. - -**To enable cloud APIs in your app** - -``` {.sourceCode .bash} -awsmobile cloud-api enable - -awsmobile push -``` - -Enabling Cloud Logic in your app adds a sample API, -`sampleCloudApi`{.sourceCode} to your project that can be used for -testing. - -You can find the sample handler function for the API by running -`awsmobile console`{.sourceCode} in your app root folder, and then -choosing the Cloud Logic feature in your project. - -![View your sample cloud API and its lambda function handler.](images/web-view-cloud-api.png) - -### Quickly Test Your API From the CLI - -The `sampleCloudApi`{.sourceCode} and its handler function allow you to -make end to end API calls. - -**To test invocation of your unsigned APIs in the development -environment** - -``` {.sourceCode .bash} -awsmobile cloud-api invoke [init] -``` - -For the `sampleCloudApi`{.sourceCode} you may use the following examples -to test the `post`{.sourceCode} method - -``` {.sourceCode .bash} -awsmobile cloud-api invoke sampleCloudApi post /items '{"body": {"testKey":"testValue"}}' -``` - -This call will return a response similar to the following. - -``` {.sourceCode .bash} -{ success: 'post call succeed!', -url: '/items', -body: { testKey: 'testValue' } } -``` - -**To test the :get method** - -``` {.sourceCode .bash} -awsmobile cloud-api invoke sampleCloudApi get /items -``` - -This will return a response as follows. - -``` {.sourceCode .bash} -{ success: 'get call succeed!', url: '/items' } -``` - -Connect to Your Backend ------------------------ - -Once you have created your own Cloud Logic <cloud-logic> APIs and -Lambda functions, you can call them from your app. - -**To call APIs from your app** - -In App.js (or other code that runs at launch-time), add the following -import. - -``` {.sourceCode .java} -import Amplify, { API } from 'aws-amplify'; -import aws_exports from './aws-exports'; -Amplify.configure(aws_exports); -``` - -Then add this to the component that calls your API. - -``` {.sourceCode .java} -state = { apiResponse: null }; - -async getSample() { - const path = "/items"; // you can specify the path - const apiResponse = await API.get("sampleCloudApi" , path); //replace the API name - console.log('response:' + apiResponse); - this.setState({ apiResponse }); -} -``` - -To invoke your API from a UI element, add an API call from within your -component's `render()`{.sourceCode} method. - -``` {.sourceCode .html} - - - ``` - -Open your app locally and test out guessing the number by running -`awsmobile run`{.sourceCode}. - -Your entire component should look like the following: - -### Next Steps - -- Learn how to retrieve specific items and more with the [API module - in AWS - Amplify](https://aws.github.io/aws-amplify/media/developer_guide.html). -- Learn how to enable more features for your app with the [AWS Mobile - CLI](https://aws.github.io/aws-amplify). -- Learn more about what happens behind the scenes, see [Set up Lambda - and API - Gateway](https://alpha-docs-aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html). - diff --git a/docs/media/getting-started/web-access-databases.rst.md b/docs/media/getting-started/web-access-databases.rst.md deleted file mode 100644 index 2a2a756af36..00000000000 --- a/docs/media/getting-started/web-access-databases.rst.md +++ /dev/null @@ -1,211 +0,0 @@ -Access Your Database -==================== - -The AWS Mobile CLI and Amplify library make it easy to perform create, -read, update, and delete ("CRUD") actions against data stored in the -cloud through simple API calls in your JavaScript app. - -Set Up Your Backend -------------------- - -**To create a database** - -1. Enable the NoSQL database feature and configure your table. - - In the root folder of your app, run: - - ``` {.sourceCode .bash} - awsmobile database enable --prompt - ``` - -2. Choose `Open`{.sourceCode} to make the data in this table viewable - by all users of your application. - - ``` {.sourceCode .bash} - ? Should the data of this table be open or restricted by user? - ❯ Open - Restricted - ``` - -3. For this example type in todos as your `Table name`{.sourceCode}. - - ``` {.sourceCode .bash} - ? Table name: todos - ``` - -### Add columns and queries - -You are creating a table in a [NoSQL -database](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SQLtoNoSQL.html) -and adding an initial set of columns, each of which has a name and a -data type. NoSQL lets you add a column any time you store data that -contains a new column. NoSQL tables must have one column defined as the -Primary Key, which is a unique identifier for each row. - -1. For this example, follow the prompts to add three columns: team - (string), todoId (number), and text (string). - - ``` {.sourceCode .bash} - ? What would you like to name this column: team - ? Choose the data type: string - ``` - -2. When prompted to `? Add another column`{.sourceCode}, type Y and - then choose enter. Repeat the steps to create todoId and text - columns. -3. Select `team`{.sourceCode} as the primary key. - - ``` {.sourceCode .bash} - ? Select primary key - ❯ team - todoId - text - ``` - -4. Choose `(todoId)`{.sourceCode} as the sort key and then - `no`{.sourceCode} to adding any more indexes, to keep the example - simple. - - ``` {.sourceCode .bash} - ? Select sort key - ❯ todoId - text - (No Sort Key) - - ? Add index (Y/n): n - Table todos saved. - ``` - - The `todos`{.sourceCode} table is now created. - -### Use a cloud API to do CRUD operations - -To access your NoSQL database, you will create an API that can be called -from your app to perform CRUD operations. - -**To create a CRUD API** - -1. Enable and configure the Cloud Logic feature\*\* - - ``` {.sourceCode .bash} - awsmobile cloud-api enable --prompt - ``` - -2. Choose - `Create CRUD API for an existing Amazon DynamoDB table`{.sourceCode} - API for an exisitng Amazon DynamoDB table" and then choose enter. - - ``` {.sourceCode .bash} - ? Select from one of the choices below. (Use arrow keys) - Create a new API - ❯ Create CRUD API for an existing Amazon DynamoDB table - ``` - -3. Select the `todos`{.sourceCode} table created in the previous steps, - and choose enter. - - ``` {.sourceCode .bash} - ? Select Amazon DynamoDB table to connect to a CRUD API - ❯ todos - ``` - -4. Push your configuration to the cloud. Without this step, the - configuration for your database and API is now in place only on your - local machine. - - ``` {.sourceCode .bash} - awsmobile push - ``` - - The required DynamoDB tables, API Gateway endpoints, and Lambda - functions will now be created. - -### Create your first Todo - -The AWS Mobile CLI enables you to test your API from the command line. - -Run the following command to create your first todo. - -``` {.sourceCode .bash} -awsmobile cloud-api invoke todosCRUD POST /todos '{"body": {"team": "React", "todoId": 1, "text": "Learn more Amplify"}}' -``` - -Connect to Your Backend ------------------------ - -The examples in this section show how you would integrate AWS Amplify -library calls using React (see the [AWS Amplify -documentation](https://aws.github.io/aws-amplify/) to use other flavors -of Javascript). - -The following component is a simple Todo list that you might add to a -`create-react-app`{.sourceCode} project. The Todos component currently -adds and displays `todos`{.sourceCode} to and from an in memory array. - -### Displaying todos from the cloud - -The `API`{.sourceCode} module from AWS Amplify allows you connect to -DynamoDB through endpoints. - -**To retrieve and display items in a database** - -1. Import the `API`{.sourceCode} module from `aws-amplify`{.sourceCode} - at the top of the Todos component file. - - ``` {.sourceCode .javascript} - import { API } from 'aws-amplify'; - ``` - -2. Add the following `componentDidMount`{.sourceCode} to the - `Todos`{.sourceCode} component to fetch all of the - `todos`{.sourceCode}. - - ``` {.sourceCode .javascript} - async componentDidMount() { - let todos = await API.get('todosCRUD', `/todos/${this.state.team}`); - this.setState({ todos }); - } - ``` - -When the `Todos`{.sourceCode} component mounts it will fetch all of the -`todos`{.sourceCode} stored in your database and display them. - -### Saving todos to the cloud - -The following fragment shows the `saveTodo`{.sourceCode} function for -the Todo app. - -``` {.sourceCode .javascript} -async saveTodo(event) { - event.preventDefault(); - - const { team, todos } = this.state; - const todoId = todos.length + 1; - const text = this.refs.newTodo.value; - - const newTodo = {team, todoId, text}; - await API.post('todosCRUD', '/todos', { body: newTodo }); - todos.push(newTodo); - this.refs.newTodo.value = ''; - this.setState({ todos, team }); -} -``` - -Update the `form`{.sourceCode} element in the component's render -function to invoke the `saveTodo`{.sourceCode} function when the form is -submitted. - -``` {.sourceCode .javascript} - -``` - -Your entire component should look like the following: - -#### Next Steps - -- Learn how to retrieve specific items and more with the [API module - in AWS - Amplify](https://aws.github.io/aws-amplify/media/developer_guide.html). -- Learn how to enable more features for your app with the [AWS Mobile - CLI](https://aws.github.io/aws-amplify). - diff --git a/docs/media/getting-started/web-add-analytics.rst.md b/docs/media/getting-started/web-add-analytics.rst.md deleted file mode 100644 index c3431a4109f..00000000000 --- a/docs/media/getting-started/web-add-analytics.rst.md +++ /dev/null @@ -1,101 +0,0 @@ -Add Analytics -============= - -Basic Analytics Backend is Enabled for Your App ------------------------------------------------ - -When you complete the AWS Mobile CLI setup and launch your app, -anonymized session and device demographics data flows to the AWS -analytics backend. - -**To send basic app usage analytics to AWS** - -Launch your app locally by running: - -``` {.sourceCode .bash} -npm start -``` - -When you use your app the [Amazon -Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/) -service gathers and visualizes analytics data. - -**To view the analytics using the Amazon Pinpoint console** - -1. Run `npm start`{.sourceCode}, `awsmobile run`{.sourceCode}, or - `awsmobile publish --test`{.sourceCode} at least once. -2. Open your project in the [AWS Mobile Hub - console](https://console.aws.amazon.com/mobilehub/). - - ``` {.sourceCode .bash} - awsmobile console - ``` - -3. Choose the Analytics icon on the left, to navigate to your project - in the [Amazon Pinpoint - console](https://console.aws.amazon.com/pinpoint/). -4. Choose Analytics on the left. - -You should see an up-tick in several graphs. - -Add Custom Analytics to Your App --------------------------------- - -You can configure your app so that [Amazon -Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/) -gathers data for custom events that you register within the flow of your -code. - -**To instrument custom analytics in your app** - -In the file containing the event you want to track, add the following -import: - -``` {.sourceCode .java} -import { Analytics } from 'aws-amplify'; -``` - -Add the a call like the following to the spot in your JavaScript where -the tracked event should be fired: - -``` {.sourceCode .javascript} -componentDidMount() { - Analytics.record('FIRST-EVENT-NAME'); -} -``` - -Or to relevant page elements: - -``` {.sourceCode .html} -handleClick = () => { - Analytics.record('SECOND-EVENT-NAME'); -} - - -``` - -To test: - -1. Save the changes and run `npm start`{.sourceCode}, - `awsmobile run`{.sourceCode}, or - `awsmobile publish --test`{.sourceCode} to launch your app. Use your - app so that tracked events are triggered. -2. In the [Amazon Pinpoint - console](https://console.aws.amazon.com/pinpoint/), choose Events - near the top. -3. Select an event in the Event dropdown menu on the left. - -Custom event data may take a few minutes to become visible in the -console. - -Next Steps ----------- - -Learn more about the analytics in AWS Mobile which are part of the -Messaging and Analytics <messaging-and-analytics> feature. This -feature uses [Amazon -Pinpoint](http://docs.aws.amazon.com/pinpoint/latest/developerguide/welcome.html). - -Learn about AWS Mobile CLI <aws-mobile-cli-reference>. - -Learn about [AWS Mobile Amplify](https://aws.github.io/aws-amplify). diff --git a/docs/media/getting-started/web-add-storage.rst.md b/docs/media/getting-started/web-add-storage.rst.md deleted file mode 100644 index ccee07c2a6d..00000000000 --- a/docs/media/getting-started/web-add-storage.rst.md +++ /dev/null @@ -1,120 +0,0 @@ -Add Storage -=========== - -The AWS Mobile CLI and AWS Amplify library make it easy to store and -manage files in the cloud from your JavaScript app. - -Set Up the Backend ------------------- - -Enable the User File Storage feature by running the following commands -in the root folder of your app. - -``` {.sourceCode .bash} -awsmobile user-files enable - -awsmobile push -``` - -Connect to the Backend ----------------------- - -The examples in this section show how you would integrate AWS Amplify -library calls using React (see the [AWS Amplify -documentation](https://aws.github.io/aws-amplify) to use other flavors -of Javascript). - -The following simple component could be added to a -`create-react-app`{.sourceCode} project to present an interface that -uploads images and download them for display. - -### Upload a file - -The `Storage`{.sourceCode} module enables you to upload files to the -cloud. All uploaded files are publicly viewable by default. - -Import the `Storage`{.sourceCode} module in your component file. - -``` {.sourceCode .javascript} -// ./src/ImageViewer.js - -import { Storage } from 'aws-amplify'; -``` - -Add the following function to use the `put`{.sourceCode} function on the -`Storage`{.sourceCode} module to upload the file to the cloud, and set -your component’s state to the name of the file. - -``` {.sourceCode .javascript} -uploadFile(event) { - const file = event.target.files[0]; - const name = file.name; - - Storage.put(key, file).then(() => { - this.setState({ file: name }); - }); -} -``` - -Place a call to the `uploadFile`{.sourceCode} function in the -`input`{.sourceCode} element of the component’s render function, to -start upload when a user selects a file. - -``` {.sourceCode .javascript} -render() { - return ( -
-

Pick a file

- -
- ); -} -``` - -### Display an image - -To display an image, this example shows the use of the -`S3Image`{.sourceCode} component of the AWS Amplify for React library. - -1. From a terminal, run the following command in the root folder of - your app. - - ``` {.sourceCode .bash} - npm install --save aws-amplify-react - ``` - -2. Import the `S3Image`{.sourceCode} module in your component. - - ``` {.sourceCode .javascript} - import { S3Image } from 'aws-amplify-react'; - ``` - -Use the S3Image component in the render function. Update your render -function to look like the following: - -``` {.sourceCode .javascript} -render() { - return ( -
-

Pick a file

- - { this.state && } -
- ); -} -``` - -#### Next Steps - -- Learn how to do private file storage and more with the [Storage - module in AWS - Amplify](https://aws.github.io/aws-amplify/media/developer_guide.html). -- Learn how to enable more features for your app with the [AWS Mobile - CLI](https://aws.github.io/aws-amplify). -- Learn how to use those features in your app with the [AWS Amplify - library](https://aws.github.io/aws-amplify). -- Learn more about the [analytics for the User File Storage - feature](https://alpha-docs-aws.amazon.com/pinpoint/latest/developerguide/welcome.html). -- Learn more about how your files are stored on [Amazon Simple Storage - Service](https://aws.amazon.com/documentation/s3/). - diff --git a/docs/media/getting-started/web-add-user-sign-in.rst.md b/docs/media/getting-started/web-add-user-sign-in.rst.md deleted file mode 100644 index c4d47b082b3..00000000000 --- a/docs/media/getting-started/web-add-user-sign-in.rst.md +++ /dev/null @@ -1,59 +0,0 @@ -Add Auth / User Sign-in -======================= - -Set Up Your Backend -------------------- - -The AWS Mobile CLI components for user authentication include a rich, -configurable UI for sign-up and sign-in. - -**To enable the Auth features** - -In the root folder of your app, run: - -``` {.sourceCode .java} -awsmobile user-signin enable - -awsmobile push -``` - -Connect to Your Backend ------------------------ - -The AWS Mobile CLI enables you to integrate ready-made -sign-up/sign-in/sign-out UI from the command line. - -**To add user auth UI to your app** - -1. Install AWS Amplify for React library. - - ``` {.sourceCode .bash} - npm install --save aws-amplify-react - ``` - -2. Add the following import in App.js (or other file that runs upon app - startup): - - ``` {.sourceCode .java} - import { withAuthenticator } from 'aws-amplify-react'; - ``` - -3. Then change `export default App;`{.sourceCode} to the following. - - ``` {.sourceCode .java} - export default withAuthenticator(App); - ``` - -To test, run `npm start`{.sourceCode}, `awsmobile run`{.sourceCode}, or -`awsmobile publish --test`{.sourceCode}. - -Next Steps ----------- - -Learn more about the AWS Mobile User Sign-in <user-sign-in> -feature, which uses [Amazon -Cognito](http://docs.aws.amazon.com/cognito/latest/developerguide/welcome.html). - -Learn about AWS Mobile CLI <aws-mobile-cli-reference>. - -Learn about [AWS Mobile Amplify](https://aws.github.io/aws-amplify). diff --git a/docs/media/getting-started/web-aws-mobile-reference.rst.md b/docs/media/getting-started/web-aws-mobile-reference.rst.md deleted file mode 100644 index c59919dcd0a..00000000000 --- a/docs/media/getting-started/web-aws-mobile-reference.rst.md +++ /dev/null @@ -1,5 +0,0 @@ -Features -======== - -The following pages contain reference material for the AWS Mobile CLI -for Web (JavaScript). diff --git a/docs/media/getting-started/web-getting-started.rst.md b/docs/media/getting-started/web-getting-started.rst.md deleted file mode 100644 index 98eeaf66709..00000000000 --- a/docs/media/getting-started/web-getting-started.rst.md +++ /dev/null @@ -1,199 +0,0 @@ -Get Started -=========== - -Overview --------- - -The AWS Mobile CLI provides a command line experience that allows -frontend JavaScript developers to quickly create and integrate AWS -backend resources into their mobile apps. - -Prerequisites -------------- - -1. [Sign up for the AWS Free Tier](https://aws.amazon.com/free/). -2. Install [Node.js](https://nodejs.org/en/download/) with NPM. -3. Install AWS Mobile CLI - - ``` {.sourceCode .bash} - npm install -g awsmobile-cli - ``` - -4. Configure the CLI with your AWS credentials - - To setup permissions for the toolchain used by the CLI, run: - - ``` {.sourceCode .bash} - awsmobile configure - ``` - - If prompted for credentials, follow the steps provided by the CLI. - For more information, see - provide IAM credentials to AWS Mobile CLI <aws-mobile-cli-credentials>. - -Set Up Your Backend -------------------- - -**To configure backend features for your app** - -1. In the root folder of your app, run: - - ``` {.sourceCode .bash} - awsmobile init - ``` - - The `init`{.sourceCode} command creates a backend project for your - app. By default, analytics and web hosting are enabled in your - backend and this configuration is automatically pulled into your app - when you initialize. - -2. When prompted, provide the source directory for your project. The - CLI will generate aws-exports.js in this location. This file - contains the configuration and endpoint metadata used to link your - frontend to your backend services. - - ``` {.sourceCode .bash} - ? Where is your project's source directory: src - ``` - -3. Respond to further prompts with the following values. - - ``` {.sourceCode .bash} - ? Where is your project's distribution directory to store build artifacts: build - ? What is your project's build command: npm run-script build - ? What is your project's start command for local test run: npm run-script start - ? What awsmobile project name would you like to use: YOUR-APP-NAME-2017-11-10-15-17-48 - ``` - -After the project is created you will get a success message which also -includes details on the path where the aws-exports.js is copied. - -> ``` {.sourceCode .bash} -> awsmobile project's details logged at: awsmobilejs/#current-backend-info/backend-details.json -> awsmobile project's access information logged at: awsmobilejs/#current-backend-info/aws-exports.js -> awsmobile project's access information copied to: src/aws-exports.js -> awsmobile project's specifications logged at: awsmobilejs/#current-backend-info/mobile-hub-project.yml -> contents in #current-backend-info/ is synchronized with the latest information in the aws cloud -> ``` - -Your project is now initialized. - -
.. \_web-getting-started-configure-aws-amplify: - -Connect to Your Backend ------------------------ - -AWS Mobile uses the open source [AWS Amplify -library](https://aws.github.io/aws-amplify) to link your code to the AWS -features configured for your app. - -This section of the guide shows examples using a React application of -the kind output by `create-react-app`{.sourceCode} or a similar tool. - -**To connect the app to your configured AWS features** - -In index.js (or in other code that runs at launch-time), add the -following imports. - -``` {.sourceCode .javascript} -import Amplify from 'aws-amplify'; -import awsmobile from './YOUR-PATH-TO/aws-exports'; -``` - -Then add the following code. - -``` {.sourceCode .javascript} -Amplify.configure(awsmobile); -``` - -### Run Your App Locally - -Your app is now ready to launch and use the default features configured -by AWS Mobile. - -**To launch your app locally in a browser** - -In the root folder of your app, run: - -``` {.sourceCode .bash} -awsmobile run -``` - -Behind the scenes, this command runs `npm install`{.sourceCode} to -install the Amplify library and also pushes any backend configuration -changes to AWS Mobile. To run your app locally without pushing backend -changes you cou can choose to run `npm install`{.sourceCode} and then -run `npm start`{.sourceCode}. - -Anytime you launch your app, -app analytics are gathered and can be visualized<web-add-analytics> -in an AWS console. - -Next Steps ----------- - -### Deploy your app to the cloud - -Using a simple command, you can publish your app's frontend to hosting -on a robust content distribution network (CDN) and view it in a browser. - -**To deploy your app to the cloud and launch it in a browser** - -In the root folder of your app, run: - -``` {.sourceCode .bash} -awsmobile publish -``` - -To push any backend configuration changes to AWS and view content -locally, run `awsmobile run`{.sourceCode}. In both cases, any pending -changes you made to your backend configuration are made to your backend -resources. - -By default, the CLI configures AWS Mobile -Hosting and Streaming <hosting-and-streaming> feature, that hosts -your app on [Amazon CloudFront](https://aws.amazon.com/cloudfront/) CDN -endpoints. These locations make your app highly available to the public -on the Internet and support [media file -streaming](http://docs.aws.amazon.com/mobile-hub/latest/developerguide/url-cf-dev;Tutorials.html) - -You can also use a custom domain <web-host-frontend> for your -hosting location. - -### Test Your App on Our Mobile Devices - -Invoke a free remote test of your app on a variety of real devices and -see results, including screen shots. - -**To invoke a remote test of your app** - -In the root folder of your app, run: - -``` {.sourceCode .bash} -awsmobile publish --test -``` - -The CLI will open the reporting page for your app in the console to show -the metrics gathered from the test devices. The device that runs the -remote test you invoke resides in [AWS Device -Farm](https://aws.amazon.com/device-farm/) which provides flexible -configuration of tests and reporting. - -![image](images/web-performance-testing.png) - -### Add Features - -Add the following AWS Mobile features to your mobile app using the CLI. - -> - Analytics <web-add-analytics> -> - User Sign-in <web-add-user-sign-in> -> - NoSQL Database <web-access-databases> -> - User File Storage <web-add-storage> -> - Cloud Logic <web-access-apis> - -### Learn more - -To learn more about the commands and usage of the AWS Mobile CLI, see -the AWS Mobile CLI reference<aws-mobile-cli-reference>. - -Learn about [AWS Mobile Amplify](https://aws.github.io/aws-amplify). diff --git a/docs/media/getting-started/web-host-frontend.rst.md b/docs/media/getting-started/web-host-frontend.rst.md deleted file mode 100644 index 98f0b543f22..00000000000 --- a/docs/media/getting-started/web-host-frontend.rst.md +++ /dev/null @@ -1,69 +0,0 @@ -Access Your APIs -================ - -About Hosting and Streaming ---------------------------- - -The AWS Mobile Hosting and Streaming <hosting-and-streaming> -feature is especially useful to web developers. It uses the ability of -[Amazon -S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html) -buckets to statically host content and the [Amazon -CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) -content distribution network (CDN) to host on an endpoint close to every -user globally. Amazon CloudFront endpoints can also stream media -content. - -**About the Hosting and Streaming Sample App** - -When you enable Hosting and Streaming , provisions content in the root -of your source bucket which includes a local copy of the (aws-min.js). - -- aws-sdk.min.js - An source file. -- aws-config.js,- A web app configuration file that is generated to - contain constants for the endpoints for each feature you have - enabled for this project. -- index.html - Which uses a constant formed in aws-config.js to - request and display an AWS guest (unauthenticated) user identity ID - from the service. - -When you enable Hosting and Streaming an global content delivery network -(CDN) distribution is created and associated with your bucket. When -propagates the sample web app content to the bucket, the content is then -propagated to the CDN and becomes available from local endpoints around -the globe. If you configure [CloudFront -streaming](http://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Tutorials.html), -then media content you upload to your bucket can be streamed from those -endpoints. - -\*\* To view the Hosting and Streaming Sample App - -The Hosting and Streaming feature creates a sample JavaScript web app -that demonstrates connecting to the AWS resources of your project. - -The sample app web assets are deployed to an bucket. The bucket is -configured to host static web content for public access. - -1. In the [Mobile Hub - console](https://console.aws.amazon.com/mobilehub/home/), open your - project and then choose the Hosting and Streaming tile. -2. Choose View from S3. - - This opens a browser and displays the index.html of the sample web - app from the bucket. - - > ![Image of the |AMH| console.](images/add-aws-mobile-add-hosting-and-streaming-view-from-s3.png) - -Configure a Custom Domain for Your Web App ------------------------------------------- - -> To use your custom domain for linking to your Web app, use the service -> to configure DNS routing. -> -> For a web app hosted in a single location, see [Routing Traffic to a -> Website that Is Hosted in an Amazon S3 -> Bucket](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/RoutingToS3Bucket.html). -> -> For a web app distributed through a global CDN, see [Routing Traffic -> to an Amazon CloudFront Web Distribution by Using Your Domain -> Name](http://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloud-fron-distribution.html)