|
| 1 | +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; |
| 2 | + |
| 3 | +export const meta = { |
| 4 | + title: 'Configure a geofence collection', |
| 5 | + description: 'Use Amplify CLI to create and manage collections of Geofences', |
| 6 | + platforms: [ |
| 7 | + 'android', |
| 8 | + 'angular', |
| 9 | + 'javascript', |
| 10 | + 'nextjs', |
| 11 | + 'react', |
| 12 | + 'swift', |
| 13 | + 'vue' |
| 14 | + ] |
| 15 | +}; |
| 16 | + |
| 17 | +export const getStaticPaths = async () => { |
| 18 | + return getCustomStaticPath(meta.platforms); |
| 19 | +}; |
| 20 | + |
| 21 | +export function getStaticProps(context) { |
| 22 | + return { |
| 23 | + props: { |
| 24 | + platform: context.params.platform, |
| 25 | + meta |
| 26 | + } |
| 27 | + }; |
| 28 | +} |
| 29 | + |
| 30 | +A Geofence is a virtual perimeter for a real-world geographic area. A Geofence contains points or vertices that form a closed boundary, defining an area of interest. Geofence collections store one or multiple Geofences. Amplify's `geo` category enables you to create and manage Geofence collections used to setup virtual geographic perimeters. |
| 31 | + |
| 32 | +## Setup a new Geofence Collection |
| 33 | + |
| 34 | +Before you add a new Geofence Collection to your application, you need to have at least one Cognito User Pool group added to your project. The permissions to perform `CRUD` operations on Geofences in the collection will be granted only to users belonging to a Cognito User Pool group that is responsible for managing these Geofences. |
| 35 | + |
| 36 | +If you haven't set up the `auth` category already, you can do so by running: |
| 37 | + |
| 38 | +```bash |
| 39 | +amplify add auth |
| 40 | +``` |
| 41 | + |
| 42 | +When you have `auth` category set up, you can add the Cognito User Pool groups using: |
| 43 | + |
| 44 | +```bash |
| 45 | +amplify update auth |
| 46 | +``` |
| 47 | + |
| 48 | +```console |
| 49 | +? What do you want to do? |
| 50 | + Apply default configuration with Social Provider (Federation) |
| 51 | + Walkthrough all the auth configurations |
| 52 | +❯ Create or update Cognito user pool groups |
| 53 | + Create or update Admin queries API |
| 54 | + |
| 55 | +? Provide a name for your user pool group: storesInWashingtonGeofenceCollectionAdmin |
| 56 | + |
| 57 | +? Do you want to add another User Pool Group No |
| 58 | + |
| 59 | +? Sort the user pool groups in order of preference |
| 60 | + storesInWashingtonGeofenceCollectionAdmin |
| 61 | + |
| 62 | +``` |
| 63 | + |
| 64 | +If you want to grant access to previously created geo resources to the users of the Cognito group added above, follow the instructions as mentioned [in the section below](#granting-maps-and-search-permissions-to-a-group-of-users). |
| 65 | + |
| 66 | +Additionally, if you want to add existing users to the Cognito group, follow the instructions as mentioned [in the section below](#adding-users-to-a-cognito-user-pool-group). |
| 67 | + |
| 68 | +When you have at least one Cognito User Pool group added, you can now provision a new Geofence Collection using: |
| 69 | + |
| 70 | +```bash |
| 71 | +amplify add geo |
| 72 | +``` |
| 73 | + |
| 74 | +```console |
| 75 | +? Select which capability you want to add: |
| 76 | + Map (visualize the geospatial data) |
| 77 | + Location search (search by places, addresses, coordinates) |
| 78 | +❯ Geofencing (visualize virtual perimeters) |
| 79 | +``` |
| 80 | + |
| 81 | +Next, set a name for the Geofence Collection: |
| 82 | + |
| 83 | +```console |
| 84 | +? Provide a name for the Geofence Collection: storesInWashington |
| 85 | +``` |
| 86 | + |
| 87 | +## Geofence Collection Access permissions |
| 88 | + |
| 89 | +Next, configure the access permissions for your geofence collection resource and authorize users of desired Cognito User Pool groups to perform `CRUD` operations on Geofences in the collection. |
| 90 | + |
| 91 | +```console |
| 92 | +? Select one or more cognito groups to give access: |
| 93 | +✔ storesInWashingtonGeofenceCollectionAdmin |
| 94 | + |
| 95 | +? What kind of access do you want for storesInWashingtonGeofenceCollectionAdmin users? Select ALL that apply: |
| 96 | + ✔ Read geofence |
| 97 | + ✔ Create/Update geofence |
| 98 | + Delete geofence |
| 99 | + ✔ List geofences |
| 100 | +``` |
| 101 | + |
| 102 | +The above chosen permissions are granted to the users belonging the specified Cognito User Pool group. Please note that these permissions apply to ALL Geofences in a collection. For example, If you chose `Read geofence` permission for say `storesInWashingtonGeofenceCollectionAdmin` Cognito group, ALL users added to that group will be able to read the properties of ALL Geofences in that Geofence collection. |
| 103 | + |
| 104 | +## Geofence Collection Pricing Plan |
| 105 | + |
| 106 | +The pricing plan for the Geofence Collection will be set to `RequestBasedUsage`. We advice you to go through the [location service pricing](https://aws.amazon.com/location/pricing/) along with the [location service terms](https://aws.amazon.com/service-terms/) (_82.5 section_) to learn more about the pricing plan. |
| 107 | + |
| 108 | +## Set a default Geofence Collection |
| 109 | + |
| 110 | +If you added more than one geofence collection via `amplify add geo`, the geofence collection that was added last will be the default. However, you can choose if the current geofence collection should be the default for your application: |
| 111 | + |
| 112 | +```console |
| 113 | +? Set this geofence collection as the default? It will be used in Amplify geofence collection API calls if no explicit reference is provided. (Y/n) |
| 114 | +> No |
| 115 | +``` |
| 116 | + |
| 117 | +Answering `No` will retain the previously set default. |
| 118 | + |
| 119 | +That's it! You can now create virtual perimeters around points of interest in your application. Follow the library documentation as listed [here](/[platform]/build-a-backend/more-features/geo/geofences/). |
| 120 | + |
| 121 | +## Granting Maps and Search permissions to a group of users |
| 122 | + |
| 123 | +If you want to grant permissions to render a Map or Search for places to the users of a Cognito group, you can do so as shown below: |
| 124 | + |
| 125 | +```bash |
| 126 | +amplify update geo |
| 127 | +``` |
| 128 | + |
| 129 | +```console |
| 130 | +? Select which capability you want to update: (Use arrow keys) |
| 131 | +❯ Map (visualize the geospatial data) |
| 132 | + Location search (search by places, addresses, coordinates) |
| 133 | + Geofencing (visualize virtual perimeters) |
| 134 | + |
| 135 | +? Select the Map you want to update: |
| 136 | +❯ EsriDarkCanvasMap |
| 137 | + |
| 138 | +? Restrict access by? |
| 139 | + Auth/Guest Users |
| 140 | + Individual Groups |
| 141 | +❯ Both |
| 142 | + Learn more |
| 143 | +``` |
| 144 | + |
| 145 | +#### Auth/Guest Users access |
| 146 | + |
| 147 | +Select `Auth/Guest Users`, to scope permissions based on an individual user's authentication status. On the next question you'll be able to select if only authenticated users can access resources, or authenticated and guest users: |
| 148 | + |
| 149 | +``` |
| 150 | +? Who can access this Map? |
| 151 | +❯ Authorized users only |
| 152 | + Authorized and Guest users |
| 153 | +``` |
| 154 | + |
| 155 | +Select `Authorized users only` if only authenticated users are allowed to render the map. |
| 156 | + |
| 157 | +Select `Authorized and Guest users` if both authenticated and unauthenticated users are allowed to render the map. |
| 158 | + |
| 159 | +For more information, refer [link to location service page](https://docs.aws.amazon.com/location/latest/developerguide/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-get-map-tiles). |
| 160 | + |
| 161 | +#### Individual Group access |
| 162 | + |
| 163 | +Select `Individual Groups` to scope access permissions based on [Cognito User Groups](/[platform]/build-a-backend/graphqlapi/customize-authorization-rules/) |
| 164 | + |
| 165 | +```console |
| 166 | +? Select one or more cognito groups to give access: |
| 167 | + ✔ storesInWashingtonGeofenceCollectionAdmin |
| 168 | +``` |
| 169 | + |
| 170 | +> Note: If you combine `Auth/Guest user access` and `Individual Group access`, users who are members of a group will only be granted the permissions of the group, and not the authenticated user permissions. |
| 171 | +
|
| 172 | +## Adding users to a Cognito User Pool Group |
| 173 | + |
| 174 | +In order to add users to an existing Cognito user pool group created using Amplify CLI, follow the steps mentioned below: |
| 175 | + |
| 176 | +#### Using the AWS console |
| 177 | + |
| 178 | +Open the AWS console page corresponding to the user pool that is provisioned by Amplify CLI using |
| 179 | + |
| 180 | +```console |
| 181 | +amplify auth console |
| 182 | + |
| 183 | +? Which console |
| 184 | +❯ User Pool |
| 185 | + Identity Pool |
| 186 | + User Pool and Identity Pool |
| 187 | +``` |
| 188 | + |
| 189 | +From the Cognito user pool console page that opened in your default browser, choose `Users and groups` tab in `General settings`. Then, choose the corresponding Cognito group from the `Groups` tab on the right as shown  |
| 190 | + |
| 191 | +Then click on the `Add users` button that displays a window to select the users by their `username`, `email` etc. that you intend to add to the Cognito group. _Note: the user(s) added to the Cognito User Pool Group may need to be re-authenticated by signing out and signing in again._  |
| 192 | + |
| 193 | +#### Using the AWS SDK for Javascript |
| 194 | + |
| 195 | +Alternatively, if you want to add users to an existing Cognito user pool group programmatically, you can use the AWS SDK for Javascript. Refer to the [API documentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityServiceProvider.html#adminAddUserToGroup). |
| 196 | + |
| 197 | +## Upload your own GeoJSON file to geofence collection |
| 198 | + |
| 199 | +After you have added geofence collection and provisioned the resource, you will be able to upload your own GeoJSON file that defines the Geofences in a collection via the command: |
| 200 | + |
| 201 | +```bash |
| 202 | +amplify geo import |
| 203 | +``` |
| 204 | + |
| 205 | +You can refer to [GeoJSON.IO](https://geojson.io/) where you can draw your own geofences and have GeoJSON file auto generated. After you get the GeoJSON file, you can provide the file path: |
| 206 | + |
| 207 | +```console |
| 208 | +? Provide the path to GeoJSON file containing the Geofences for ${your_geofence_collection} collection: |
| 209 | +> ${your_input_geojson_file_path} |
| 210 | +``` |
| 211 | + |
| 212 | +For each geofence feature, it requires a unique identifier. According to the [RFC7946](https://datatracker.ietf.org/doc/html/rfc7946#section-3.2), There are two options for applying identifiers: |
| 213 | + |
| 214 | +### Root level ID |
| 215 | + |
| 216 | +This option will use auto-generated `id` field in the root level of Feature object as identifier. |
| 217 | + |
| 218 | +<Callout> |
| 219 | + |
| 220 | +**Note:** This option will UPDATE your GeoJSON file |
| 221 | + |
| 222 | +</Callout> |
| 223 | + |
| 224 | +```console |
| 225 | +? Select the property to use as the Geofence feature identifier: |
| 226 | +> Use root-level "id" field. (Auto-assigned if missing) |
| 227 | +``` |
| 228 | + |
| 229 | +### Custom properties |
| 230 | + |
| 231 | +This option allows you to choose your own fields inside `properties` of Feature object. Amplify CLI will help scan the candidate properties and provide them as options in the walkthrough. The candidate properties are chosen based on the existence of all feature objects. The identifier field should have unique values among geofences and will be validated after being selected. |
| 232 | + |
| 233 | +```console |
| 234 | +? Select the property to use as the Geofence feature identifier: |
| 235 | + Use root-level "id" field. (Auto-assigned if missing) |
| 236 | +> ${scanned_candidate_property_1} |
| 237 | + ${scanned_candidate_property_2} |
| 238 | +``` |
| 239 | + |
| 240 | +A validation of the GeoJSON file will be executed afterwards. The upload of geofences will be triggered upon the success of validation. For the regulation of GeoJSON, please refer to [RFC7946](https://datatracker.ietf.org/doc/html/rfc7946) |
| 241 | + |
| 242 | +```console |
| 243 | +✅ Successfully validated GeoJSON file. |
| 244 | +✅ Successfully added/updated Geofences in your collection |
| 245 | +``` |
| 246 | + |
| 247 | +<Callout> |
| 248 | + |
| 249 | +**Note:** After you have provisioned the Geofence Collection using Amplify CLI, depending on your application's use-case, you can also add Geofences to the provisioned Geofence Collection programmatically. Refer this [API documentation](/[platform]/build-a-backend/more-features/geo/geofences/#savegeofences) for more information. |
| 250 | + |
| 251 | +</Callout> |
0 commit comments