google_assistant 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dfd97fdfaea944f3be60796786ec4f2d9e43f8cc
-  data.tar.gz: a1d07df44788b57d8e4c7bf81cde7506cf41d1be
+  metadata.gz: 53efc649d01191b0cfdabc34974a52e124fa8b8d
+  data.tar.gz: 8668eb3b467923e6db3d1667e7ef1c0bfde46c22
 SHA512:
-  metadata.gz: b048a4da4c4e612b38b676a0622bcda406dc1e5f2b31e94a8f0ed042432285662dee80c49c633df24d3272e5fa88eb426bc4f2111ef59441deedfd7f0e08d6f2
-  data.tar.gz: e3bab745f936fcee45e80936d3b45517542bc1b3f2f9deb1b5d03461b6577792ed73462ef6b4619f73a740e85f68ed311322fd31c07a4eea107bcd7441ddb907
+  metadata.gz: bf5090c145e291632812c652f89f6fb729172def0fb3449413bbff1c262dacc0e6401a7999289a8109931521630113597ace1bc9bc7a26d24eebff8a19c172fb
+  data.tar.gz: 5faf5231646608ba776b52810d9a29ccae204c418ed04821c571f5b6407aa8846db0c3ad4a1e072ae180c8958bacedd72ff4392b63929295a6c640d7993678c7

data/README.md

@@ -46,7 +46,7 @@ class GoogleAssistantController < ApplicationController
       end
     end
 
-    render assistant_response
+    render json: assistant_response
   end
 end
 ```
@@ -107,6 +107,10 @@ assistant.intent.text do
 end
 ```
 
+### SSML
+
+SSML is Google Assistant's markup language for text to speech. It provides options to pause, interpret dates and numbers, and more. You can provide SSML responses or plain text. See [Google's documentation on SSML](https://developers.google.com/actions/reference/ssml).
+
 ### User input
 
 GoogleAssistant allows you to read the user's input using `assistant.arguments` so that you can respond appropriately.
@@ -163,9 +167,88 @@ GoogleAssistant.respond_to(params, response) do |assistant|
 end
 ```
 
-### SSML
+### User ID
 
-SSML is Google Assistant's markup language for text to speech. It provides options to pause, interpret dates and numbers, and more. You can provide SSML responses or plain text. See [Google's documentation on SSML](https://developers.google.com/actions/reference/ssml).
+You can get the user's ID. This will allow you to identify the user across conversations. It works much in the same way a cookie might work; it is possible for the user to reset that ID, so don't rely on it too much.
+
+```rb
+# Get the user's ID
+assistant.user.id
+```
+
+### Permissions
+
+You can request information about the user and their device. Google handles collecting this information, but you can provide a prompt to let the user know why you need this information. The Google Assistant API responds with the `permission` intent after a permission request.
+
+#### Name
+
+Request the user's name. This will result in a prompt to the user like:
+> So that I can address you by name, I'll just need to get your name from Google. Is that ok?
+
+```rb
+assistant.intent.main do
+  # Request the user's name
+  assistant.ask_for_permission(context: "So that I can address you by name", permissions: GoogleAssistant::Permission::NAME)
+end
+
+assistant.intent.permission do
+  if assistant.permission_granted?
+    # Get the user's name from the response
+    given_name = assistant.user.given_name
+    family_name = assistant.user.family_name
+    display_name = assistant.user.display_name
+  else
+    # The user denied permission
+  end
+end
+```
+
+#### Coarse Location
+
+Request the device's zip code and city. This will result in a prompt to the user like:
+> To provide weather information for where you live, I'll just need to get your zip code from Google. Is that ok?
+
+```rb
+assistant.intent.main do
+  # Request the device's zip code and city
+  assistant.ask_for_permission(context: "To provide weather information for where you live", permissions: GoogleAssistant::Permission::DEVICE_COARSE_LOCATION)
+end
+
+assistant.intent.permission do
+  if assistant.permission_granted?
+    # Get the device's location from the response
+    zip_code = assistant.device.zip_code
+    city = assistant.device.city
+  else
+    # The user denied permission
+  end
+end
+```
+
+#### Precise Location
+
+Request the device's precise location. This will result in a prompt to the user like:
+> So that I can find out where you sleep at night, I'll just need to get your street address from Google. Is that ok?
+
+```rb
+assistant.intent.main do
+  # Request the device's precise location
+  assistant.ask_for_permission(context: "So that I can find out where you sleep at night", permissions: GoogleAssistant::Permission::DEVICE_PRECISE_LOCATION)
+end
+
+assistant.intent.permission do
+  if assistant.permission_granted?
+    # Get the device's location from the response
+    zip_code = assistant.device.zip_code
+    city = assistant.device.city
+    formatted_address = assistant.device.formatted_address
+    latitude = assistant.device.latitude
+    longitude = assistant.device.longitude
+  else
+    # The user denied permission
+  end
+end
+```
 
 ### Testing your assistant
 

data/lib/google_assistant/argument.rb

@@ -1,11 +1,35 @@
+# frozen_string_literal: true
+
 module GoogleAssistant
   class Argument
     attr_reader :name, :raw_text, :text_value
 
+    def self.from(opts)
+      case opts["name"]
+      when "permission_granted"
+        PermissionArgument.new(opts)
+      when "text"
+        TextArgument.new(opts)
+      else
+        Argument.new(opts)
+      end
+    end
+
     def initialize(opts)
       @name = opts["name"]
       @raw_text = opts["raw_text"]
       @text_value = opts["text_value"]
     end
   end
+
+  class TextArgument < Argument
+    alias_method :value, :text_value
+  end
+
+  class PermissionArgument < Argument
+
+    def permission_granted?
+      text_value == "true"
+    end
+  end
 end

data/lib/google_assistant/assistant.rb

@@ -7,6 +7,8 @@ module GoogleAssistant
     InvalidIntent = Class.new(StandardError)
     InvalidMessage = Class.new(StandardError)
     InvalidInputPrompt = Class.new(StandardError)
+    InvalidPermission = Class.new(StandardError)
+    InvalidPermissionContext = Class.new(StandardError)
     MissingRequestInputs = Class.new(StandardError)
     MissingRequestIntent = Class.new(StandardError)
 
@@ -31,7 +33,14 @@ module GoogleAssistant
 
     def arguments
       @_arguments ||= inputs[0]["arguments"].map do |argument|
-        Argument.new(argument)
+        Argument.from(argument)
+      end
+    end
+
+    def permission_granted?
+      arguments.any? do |argument|
+        argument.is_a?(PermissionArgument) &&
+          argument.permission_granted?
       end
     end
 
@@ -39,6 +48,14 @@ module GoogleAssistant
       @_conversation ||= Conversation.new(conversation_params)
     end
 
+    def user
+      @_user ||= User.new(user_params)
+    end
+
+    def device
+      @_device ||= Device.new(device_params)
+    end
+
     def tell(message)
       raise InvalidMessage if message.nil? || message.empty?
 
@@ -57,22 +74,23 @@ module GoogleAssistant
       raise InvalidInputPrompt if prompt.nil? || prompt.empty?
 
       no_input_prompt = [*no_input_prompt].compact
-
       prompt = build_input_prompt(prompt, no_input_prompt)
-
       expected_intent = build_expected_intent(StandardIntents::TEXT)
 
-      expected_inputs = [{
-        input_prompt: prompt,
-        possible_intents: [expected_intent]
-      }]
+      build_ask_response(prompt, expected_intent)
+    end
 
-      build_response(
-        conversation.dialog_state,
-        true,
-        expected_inputs,
-        nil
-      )
+    def ask_for_permission(context:, permissions:)
+      raise InvalidPermissionContext if context.nil? || context.empty?
+
+      permissions = [*permissions].compact
+      raise InvalidPermission unless Permission.valid?(permissions)
+      raise InvalidPermission if permissions.size == 0
+
+      prompt = build_input_prompt("placeholder for permission")
+      expected_intent = build_expected_intent(StandardIntents::PERMISSION, permissions, context)
+
+      build_ask_response(prompt, expected_intent)
     end
 
     private
@@ -92,6 +110,20 @@ module GoogleAssistant
       }
     end
 
+    def build_ask_response(prompt, expected_intent)
+      expected_inputs = [{
+        input_prompt: prompt,
+        possible_intents: [expected_intent]
+      }]
+
+      build_response(
+        conversation.dialog_state,
+        true,
+        expected_inputs,
+        nil
+      )
+    end
+
     def build_response(dialog_state, expect_user_response, expected_input, final_response)
       response = {}
 
@@ -103,10 +135,21 @@ module GoogleAssistant
       response
     end
 
-    def build_expected_intent(intent)
+    def build_expected_intent(intent, permissions = nil, context = nil)
       raise InvalidIntent if intent.nil? || intent.empty?
 
-      { intent: intent }
+      expected_intent = { intent: intent }
+
+      unless context.nil? || permissions.nil?
+        expected_intent[:input_value_spec] = {
+          permission_value_spec: {
+            opt_context: context,
+            permissions: permissions
+          }
+        }
+      end
+
+      expected_intent
     end
 
     def is_ssml?(text)
@@ -130,5 +173,13 @@ module GoogleAssistant
     def conversation_params
       params["conversation"] || {}
     end
+
+    def user_params
+      params["user"] || {}
+    end
+
+    def device_params
+      params["device"] || {}
+    end
   end
 end

data/lib/google_assistant/device.rb

@@ -0,0 +1,30 @@
+module GoogleAssistant
+  class Device
+    attr_reader :location, :coordinates
+
+    def initialize(opts)
+      @location = opts["location"] || {}
+      @coordinates = @location["coordinates"] || {}
+    end
+
+    def city
+      location["city"]
+    end
+
+    def zip_code
+      location["zip_code"]
+    end
+
+    def formatted_address
+      location["formatted_address"]
+    end
+
+    def latitude
+      coordinates["latitude"]
+    end
+
+    def longitude
+      coordinates["longitude"]
+    end
+  end
+end

data/lib/google_assistant/intent.rb

@@ -28,6 +28,10 @@ module GoogleAssistant
       intents[StandardIntents::TEXT] = block
     end
 
+    def permission(&block)
+      intents[StandardIntents::PERMISSION] = block
+    end
+
     def call
       block = intents[intent_string]
       return if block.nil?

data/lib/google_assistant/permission.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module GoogleAssistant
+  module Permission
+    NAME = "NAME"
+    DEVICE_PRECISE_LOCATION = "DEVICE_PRECISE_LOCATION"
+    DEVICE_COARSE_LOCATION = "DEVICE_COARSE_LOCATION"
+
+    def self.valid?(permissions)
+      permissions = [*permissions]
+      permissions.all? do |permission|
+        [NAME, DEVICE_PRECISE_LOCATION, DEVICE_COARSE_LOCATION].include?(permission)
+      end
+    end
+  end
+end

data/lib/google_assistant/user.rb

@@ -0,0 +1,22 @@
+module GoogleAssistant
+  class User
+    attr_reader :id, :profile
+
+    def initialize(opts)
+      @id = opts["user_id"]
+      @profile = opts["profile"] || {}
+    end
+
+    def display_name
+      profile["display_name"]
+    end
+
+    def given_name
+      profile["given_name"]
+    end
+
+    def family_name
+      profile["family_name"]
+    end
+  end
+end

data/lib/google_assistant/version.rb

@@ -1,3 +1,3 @@
 module GoogleAssistant
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google_assistant
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron Milam
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-13 00:00:00.000000000 Z
+date: 2017-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -73,8 +73,11 @@ files:
 - lib/google_assistant/argument.rb
 - lib/google_assistant/assistant.rb
 - lib/google_assistant/conversation.rb
+- lib/google_assistant/device.rb
 - lib/google_assistant/dialog_state.rb
 - lib/google_assistant/intent.rb
+- lib/google_assistant/permission.rb
+- lib/google_assistant/user.rb
 - lib/google_assistant/version.rb
 homepage: https://github.com/armilam/google-assistant-ruby
 licenses: