docs/manual/source/templates/leadscoring/quickstart.html.md.erb

---
title: Quick Start - Lead Scoring Engine Template
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

## Overview

This engine template predicts the probability of an user will convert (conversion event by user) in the current session.

WARNING: This template requires PredictionIO version >= 0.9.0

## Usage

### Event Data Requirements

By default, the template requires the following events to be collected:

- 'page view' events with session ID
- the first page view event can optionally provide the browser and referrer ID
- user 'buy' event with session ID

The landing page ID, referrer ID, browser information and user's buy event will be used to train the model.

NOTE: You can customize what the "conversion" event is. It's "buy" item event by default but it can be modified to others such as "subscribe".

### Input Query

- Landing page ID
- Referrer ID
- Browser

### Output PredictedResult

- score

## 1. Install and Run PredictionIO

<%= partial 'shared/quickstart/install' %>

## 2. Create a new Engine from an Engine Template

<%= partial 'shared/quickstart/create_engine', locals: { engine_name: 'MyLeadScoring', template_name: 'Lead Scoring Engine Template', template_repo: 'PredictionIO/template-scala-parallel-leadscoring' } %>

## 3. Generate an App ID and Access Key

<%= partial 'shared/quickstart/create_app' %>

## 4. Collecting Data

Next, let's collect training data for this Engine. By default,
 Lead Scoring Engine Template supports the following entities: **user**, **page**, and **item**. An user views a page, and buys an item.

Note that a "sessionId" property is required to indicate these events happen in the same session. In the first visit of a user, you should specify the optional "referrral ID" and "browser" information. These are used to determine where the user comes from and the browser information.

In summary, this template requires user-view-page event and user-buy-item events with the session ID, referrer ID and browser properties.

<%= partial 'shared/quickstart/collect_data' %>

For example, when an user with ID u0 views a URL page "example.com/page0" on time  `2014-11-02T09:39:45.618-08:00`, with session ID "akdj230fj8ass" (current time will be used if eventTime is not specified) you can send the event to Event Server. Run the following `curl` command:

<div class="tabs">
  <div data-tab="REST API" data-lang="json">
```
$ curl -i -X POST http://localhost:7070/events.json?accessKey=$ACCESS_KEY \
-H "Content-Type: application/json" \
-d '{
  "event" : "view",
  "entityType" : "user",
  "entityId" : "u0",
  "targetEntityType" : "page",
  "targetEntityId" : "example.com/page0",
  "properties" : {
    "sessionId" : "akdj230fj8ass",
    "referrerId" : "referrer0.com",
    "browser" : "Firefox"
  }
  "eventTime" : "2014-11-02T09:39:45.618-08:00"
}'
```
  </div>
  <div data-tab="Python SDK" data-lang="python">
```python
import predictionio

client = predictionio.EventClient(
  access_key=<ACCESS KEY>,
  url=<URL OF EVENTSERVER>,
  threads=5,
  qsize=500
)

# A user views a page

client.create_event(
  event="view",
  entity_type="user",
  entity_id=<USER ID>,
  target_entity_type="page",
  target_entity_id=<PAGE ID>,
  properties = {
    "sessionId": <SESSION ID>, # required
    "referrerId": <REFERRER ID>, # optinal. but should specify this if you have this information when user views the landing page
    "browser": <BROWSER> # optinal. but should specify this if you have this information when user views the landing page
  }
)
```
  </div>

  <div data-tab="PHP SDK" data-lang="php">
```php
<?php
require_once("vendor/autoload.php");
use predictionio\EventClient;

$client = new EventClient(<ACCESS KEY>, <URL OF EVENTSERVER>);

// A user views a page
$client->createEvent(array(
  'event' => 'view',
  'entityType' => 'user',
  'entityId' => <USER ID>,
  'targetEntityType' => 'page',
  'targetEntityId' => <PAGE ID>,
  'properties' => array(
    'sessionId' => <SESSION ID>,
    'referrerId' => <REFERRER ID>,
    'browser' => <BROWSER>
  )
));
?>
```
  </div>
  <div data-tab="Ruby SDK" data-lang="ruby">
```ruby
# Create a client object.
client = PredictionIO::EventClient.new(<ACCESS KEY>, <URL OF EVENTSERVER>)

# A user views a page.
client.create_event(
  'view',
  'user',
  <USER ID>, {
    'targetEntityType' => 'page',
    'targetEntityId' => <PAGE ID>,
    'properties' => {
      'sessionId' => <SESSION ID>,
      'referrerId' => <REFERRER ID>,
      'browser' => <BROWSER>
    }
  }
)
```
  </div>
  <div data-tab="Java SDK" data-lang="java">
```java
import org.apache.predictionio.Event;
import org.apache.predictionio.EventClient;

import com.google.common.collect.ImmutableList;

EventClient client = new EventClient(<ACCESS KEY>, <URL OF EVENTSERVER>);

// A user views a page
Event viewEvent = new Event()
    .event("view")
    .entityType("user")
    .entityId(<USER_ID>)
    .targetEntityType("page")
    .targetEntityId(<PAGE_ID>);
    .property("sessionId", "<SESSION ID>")
    .property("referrerId", "<REFERRER ID>")
    .property("browser", "<BROWSER>");
client.createEvent(viewEvent);
```
  </div>
</div>


In the same browsing session "akdj230fj8ass", the user with ID u0 buys an item i0 on time `2014-11-02T09:42:00.123-08:00` (current time will be used if eventTime is not specified), you can send the following buy event. Run the following `curl` command:

<div class="tabs">
  <div data-tab="REST API" data-lang="json">
```
$ curl -i -X POST http://localhost:7070/events.json?accessKey=$ACCESS_KEY \
-H "Content-Type: application/json" \
-d '{
  "event" : "buy",
  "entityType" : "user",
  "entityId" : "u0",
  "targetEntityType" : "item",
  "targetEntityId" : "i0",
  "properties" : {
    "sessionId" : "akdj230fj8ass"
  }
  "eventTime" : "2014-11-02T09:42:00.123-08:00"
}'
```
  </div>
  <div data-tab="Python SDK" data-lang="python">
```python
# A user buys an item

client.create_event(
  event="buy",
  entity_type="user",
  entity_id=<USER ID>,
  target_entity_type="item",
  target_entity_id=<ITEM ID>,
  properties = {
    "sessionId": <SESSION ID>, # required
  }
)
```
  </div>

  <div data-tab="PHP SDK" data-lang="php">
```php
<?php
// A user buys an item
$client->createEvent(array(
  'event' => 'buy',
  'entityType' => 'user',
  'entityId' => <USER ID>,
  'targetEntityType' => 'item',
  'targetEntityId' => <ITEM ID>,
  'properties' => array(
    'sessionId' => <SESSION ID>
  )
));

?>
```
  </div>
  <div data-tab="Ruby SDK" data-lang="ruby">
```ruby
# A user buys an item.
client.create_event(
  'buy',
  'user',
  <USER ID>, {
    'targetEntityType' => 'item',
    'targetEntityId' => <ITEM ID>,
    'properties' => {
      'sessionId' => <SESSION ID>
    }
  }
)
```
  </div>
  <div data-tab="Java SDK" data-lang="java">
```java
// A user buys an item
Event buyEvent = new Event()
    .event("buy")
    .entityType("user")
    .entityId(<USER_ID>)
    .targetEntityType("item")
    .targetEntityId(<ITEM_ID>)
    .property("sessionId", "<SESSION ID>");
client.createEvent(buyEvent);
```
  </div>
</div>

<%= partial 'shared/quickstart/query_eventserver' %>

### Import More Sample Data

<%= partial 'shared/quickstart/import_sample_data' %>

A Python import script `import_eventserver.py` is provided to import sample data. The sample data includes 50 sessions of events. In each session, a randomly selected user (with user ID "u1" to "u10") lands on a page (randomly selected from example.com/page1 to example.com/page20) with referrerId (randomly selected from referrer1.com to referrer10.com) and browser information. The user may view more pages, and may or may not buy an item (with item ID "i1" to "i50").

<%= partial 'shared/quickstart/install_python_sdk' %>

Make sure you are under the `MyLeadScoring` directory. Execute the following to import the data:

```
$ cd MyLeadScoring
$ python data/import_eventserver.py --access_key $ACCESS_KEY
```

You should see the following output:

```
...
User u8 buys item i13
session c347980abdf711e4b135b8e8560679ba
User u5 lands on page example.com/page11 referrer referrer4.com browser Firefox
User u5 views page example.com/page8
User u5 views page example.com/page17
User u5 buys item i5
166 events are imported.
```

<%= partial 'shared/quickstart/query_eventserver_short' %>

## 5. Deploy the Engine as a Service

<%= partial 'shared/quickstart/deploy_enginejson', locals: { engine_name: 'MyLeadScoring' } %>

<%= partial 'shared/quickstart/deploy', locals: { engine_name: 'MyLeadScoring' } %>

## 6. Use the Engine

Now, You can retrieve the results. When a user lands on your page "example.com/page9", with referrer "referrer10.com" and browser "Firefox", you can get the predicted lead score by sending this JSON '{ "landingPageId" : "example.com/page9", "referrerId" : "referrer10.com", "browser": "Firefox" }' to the deployed engine. The engine will return a JSON with the score.

Simply send a query by making a HTTP request or through the `EngineClient` of an SDK.

With the deployed engine running, open another terminal and run the following `curl` command or use SDK to send the query:

<div class="tabs">
  <div data-tab="REST API" data-lang="json">
```
$ curl -H "Content-Type: application/json" \
-d '{
  "landingPageId" : "example.com/page9",
  "referrerId" : "referrer10.com",
  "browser": "Firefox" }' \
http://localhost:8000/queries.json

```
  </div>
  <div data-tab="Python SDK" data-lang="python">
```python
import predictionio
engine_client = predictionio.EngineClient(url="http://localhost:8000")
print engine_client.send_query({
  "landingPageId" : "example.com/page9",
  "referrerId" : "referrer10.com",
  "browser": "Firefox"
})
```
  </div>
  <div data-tab="PHP SDK" data-lang="php">
```php
<?php
require_once("vendor/autoload.php");
use predictionio\EngineClient;

$client = new EngineClient('http://localhost:8000');

$response = $client->sendQuery(array(
  'landingPageId' => 'example.com/page9',
  'referrerId' => 'referrer10.com',
  'browser' => 'Firefox'
));

print_r($response);

?>
```
  </div>
  <div data-tab="Ruby SDK" data-lang="ruby">

```ruby
# Create client object.
client = PredictionIO::EngineClient.new('http://localhost:8000')

# Query PredictionIO.
response = client.send_query(
  'landingPageId' => 'example.com/page9',
  'referrerId' => 'referrer10.com',
  'browser' => 'Firefox'
)

puts response
```
  </div>
  <div data-tab="Java SDK" data-lang="java">

```java
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableList;
import com.google.gson.JsonObject;

import org.apache.predictionio.EngineClient;

// create client object
EngineClient engineClient = new EngineClient("http://localhost:8000");

// query

JsonObject response = engineClient.sendQuery(ImmutableMap.<String, Object>of(
  "landingPageId", "example.com/page9",
  "referrerId", "referrer10.com",
  "browser", "Firefox"
));
```
  </div>
</div>

The following is sample JSON response:

```
{"score":0.7466666666666667}
```

*MyLeadScoring* is now running.

<%= partial 'shared/quickstart/production' %>

#### [Next: DASE Components Explained](/templates/leadscoring/dase/)