0
# Web Analytics (Experimental)
1

2
Experimental web analytics streams providing engagement analytics data for various HubSpot objects. These streams offer insights into web interactions and engagement patterns for contacts, companies, deals, and other objects.
3

4
## Capabilities
5

6
### Base Web Analytics Stream
7

8
Foundation class for all web analytics functionality.
9

10
```python { .api }
11
class WebAnalyticsStream(HttpSubStream, BaseStream):
12
    """
13
    Base class for experimental web analytics streams.
14
    
15
    Provides web analytics data for HubSpot objects including:
16
    - Page views and session data
17
    - Engagement metrics and timing
18
    - Traffic sources and referrers
19
    - Conversion tracking
20
    - Custom event tracking
21
    """
22
```
23

24
### Contact Web Analytics
25

26
Web analytics data specifically for contact interactions.
27

28
```python { .api }
29
class ContactsWebAnalytics(WebAnalyticsStream):
30
    """
31
    Web analytics stream for contact engagement data.
32
    
33
    Provides analytics for contact interactions including:
34
    - Website page views by contacts
35
    - Session duration and behavior
36
    - Form interactions and conversions
37
    - Email engagement tracking
38
    - Contact journey analytics
39
    """
40
```
41

42
### Company Web Analytics
43

44
Web analytics data for company-level interactions.
45

46
```python { .api }
47
class CompaniesWebAnalytics(WebAnalyticsStream):
48
    """
49
    Web analytics stream for company engagement data.
50
    
51
    Provides analytics for company interactions including:
52
    - Company domain traffic analysis
53
    - Employee engagement tracking
54
    - Account-based marketing metrics
55
    - Company journey analytics
56
    - Multi-contact attribution
57
    """
58
```
59

60
### Deal Web Analytics
61

62
Web analytics data related to deal progression and engagement.
63

64
```python { .api }
65
class DealsWebAnalytics(WebAnalyticsStream):
66
    """
67
    Web analytics stream for deal-related engagement data.
68
    
69
    Provides analytics for deal interactions including:
70
    - Deal-related page views and content engagement
71
    - Prospect behavior during sales cycle
72
    - Content consumption by deal stage
73
    - Sales process analytics
74
    - Deal influence tracking
75
    """
76
```
77

78
### Ticket Web Analytics
79

80
Web analytics data for support ticket interactions.
81

82
```python { .api }
83
class TicketsWebAnalytics(WebAnalyticsStream):
84
    """
85
    Web analytics stream for ticket-related engagement data.
86
    
87
    Provides analytics for support interactions including:
88
    - Knowledge base usage patterns
89
    - Self-service behavior analytics
90
    - Support portal engagement
91
    - Ticket resolution journey tracking
92
    - Customer effort analysis
93
    """
94
```
95

96
### Engagement Web Analytics
97

98
Web analytics for specific engagement types.
99

100
```python { .api }
101
class EngagementsCallsWebAnalytics(WebAnalyticsStream):
102
    """Web analytics for call engagement interactions."""
103

104
class EngagementsEmailsWebAnalytics(WebAnalyticsStream):
105
    """Web analytics for email engagement interactions."""
106

107
class EngagementsMeetingsWebAnalytics(WebAnalyticsStream):
108
    """Web analytics for meeting engagement interactions."""
109

110
class EngagementsNotesWebAnalytics(WebAnalyticsStream):
111
    """Web analytics for note engagement interactions."""
112

113
class EngagementsTasksWebAnalytics(WebAnalyticsStream):
114
    """Web analytics for task engagement interactions."""
115
```
116

117
### Product & Sales Web Analytics
118

119
Web analytics for product and sales-related interactions.
120

121
```python { .api }
122
class ProductsWebAnalytics(WebAnalyticsStream):
123
    """
124
    Web analytics for product-related interactions.
125
    
126
    Provides analytics including:
127
    - Product page engagement
128
    - E-commerce behavior tracking
129
    - Product discovery patterns
130
    - Purchase journey analytics
131
    """
132

133
class LineItemsWebAnalytics(WebAnalyticsStream):
134
    """Web analytics for line item interactions."""
135

136
class GoalsWebAnalytics(WebAnalyticsStream):
137
    """Web analytics for goal-related interactions."""
138

139
class FeedbackSubmissionsWebAnalytics(WebAnalyticsStream):
140
    """Web analytics for feedback submission interactions."""
141
```
142

143
## Usage Examples
144

145
### Enabling Experimental Streams
146

147
```python
148
from source_hubspot import SourceHubspot
149

150
# Enable experimental streams in configuration
151
config = {
152
    "credentials": {
153
        "credentials_title": "OAuth Credentials",
154
        "client_id": "your_client_id",
155
        "client_secret": "your_client_secret",
156
        "refresh_token": "your_refresh_token"
157
    },
158
    "start_date": "2023-01-01T00:00:00Z",
159
    "enable_experimental_streams": True  # This enables web analytics streams
160
}
161

162
source = SourceHubspot(catalog=None, config=config, state=None)
163
streams = source.streams(config)
164

165
# Filter for web analytics streams
166
web_analytics_streams = [
167
    stream for stream in streams 
168
    if "WebAnalytics" in stream.__class__.__name__
169
]
170

171
print(f"Found {len(web_analytics_streams)} web analytics streams:")
172
for stream in web_analytics_streams:
173
    print(f"  - {stream.name}")
174
```
175

176
### Contact Web Analytics Analysis
177

178
```python
179
from source_hubspot.streams import ContactsWebAnalytics, API
180

181
api = API(credentials)
182

183
# Create contacts web analytics stream
184
contacts_analytics = ContactsWebAnalytics(
185
    api=api,
186
    start_date="2023-01-01T00:00:00Z",
187
    credentials=credentials
188
)
189

190
# Analyze contact engagement patterns
191
engagement_patterns = {}
192
total_sessions = 0
193

194
for record in contacts_analytics.read_records(sync_mode="full_refresh"):
195
    contact_id = record.get('contactId')
196
    session_data = record.get('sessionData', {})
197
    page_views = session_data.get('pageViews', 0)
198
    session_duration = session_data.get('sessionDurationMs', 0)
199
    
200
    if contact_id:
201
        if contact_id not in engagement_patterns:
202
            engagement_patterns[contact_id] = {
203
                'total_page_views': 0,
204
                'total_session_time': 0,
205
                'session_count': 0,
206
                'avg_session_duration': 0
207
            }
208
        
209
        engagement_patterns[contact_id]['total_page_views'] += page_views
210
        engagement_patterns[contact_id]['total_session_time'] += session_duration
211
        engagement_patterns[contact_id]['session_count'] += 1
212
        total_sessions += 1
213

214
# Calculate averages and display insights
215
print(f"Contact Web Analytics Summary:")
216
print(f"Total sessions analyzed: {total_sessions}")
217

218
high_engagement_contacts = []
219
for contact_id, data in engagement_patterns.items():
220
    if data['session_count'] > 0:
221
        data['avg_session_duration'] = data['total_session_time'] / data['session_count']
222
        data['avg_pages_per_session'] = data['total_page_views'] / data['session_count']
223
        
224
        # Identify high-engagement contacts
225
        if data['avg_pages_per_session'] > 5 or data['avg_session_duration'] > 300000:  # 5+ pages or 5+ minutes
226
            high_engagement_contacts.append((contact_id, data))
227

228
print(f"High-engagement contacts: {len(high_engagement_contacts)}")
229
```
230

231
### Company Account Analytics
232

233
```python
234
from source_hubspot.streams import CompaniesWebAnalytics
235

236
companies_analytics = CompaniesWebAnalytics(
237
    api=api,
238
    start_date="2023-01-01T00:00:00Z",
239
    credentials=credentials
240
)
241

242
# Track company-level engagement
243
company_engagement = {}
244

245
for record in companies_analytics.read_records(sync_mode="full_refresh"):
246
    company_id = record.get('companyId')
247
    domain = record.get('domain')
248
    engagement_score = record.get('engagementScore', 0)
249
    unique_visitors = record.get('uniqueVisitors', 0)
250
    
251
    if company_id:
252
        company_engagement[company_id] = {
253
            'domain': domain,
254
            'engagement_score': engagement_score,
255
            'unique_visitors': unique_visitors,
256
            'total_interactions': record.get('totalInteractions', 0)
257
        }
258

259
# Sort companies by engagement
260
sorted_companies = sorted(
261
    company_engagement.items(),
262
    key=lambda x: x[1]['engagement_score'],
263
    reverse=True
264
)
265

266
print("Top Engaged Companies:")
267
for company_id, data in sorted_companies[:10]:
268
    print(f"Company {company_id} ({data['domain']})")
269
    print(f"  Engagement Score: {data['engagement_score']}")
270
    print(f"  Unique Visitors: {data['unique_visitors']}")
271
    print(f"  Total Interactions: {data['total_interactions']}")
272
```
273

274
### Deal Journey Analytics
275

276
```python
277
from source_hubspot.streams import DealsWebAnalytics
278

279
deals_analytics = DealsWebAnalytics(
280
    api=api,
281
    start_date="2023-01-01T00:00:00Z",
282
    credentials=credentials
283
)
284

285
# Analyze content engagement by deal stage
286
deal_stage_engagement = {}
287

288
for record in deals_analytics.read_records(sync_mode="full_refresh"):
289
    deal_id = record.get('dealId')
290
    deal_stage = record.get('dealStage', 'Unknown')
291
    content_views = record.get('contentViews', [])
292
    
293
    if deal_stage not in deal_stage_engagement:
294
        deal_stage_engagement[deal_stage] = {
295
            'deals': set(),
296
            'total_content_views': 0,
297
            'content_types': {}
298
        }
299
    
300
    deal_stage_engagement[deal_stage]['deals'].add(deal_id)
301
    deal_stage_engagement[deal_stage]['total_content_views'] += len(content_views)
302
    
303
    # Categorize content types
304
    for content in content_views:
305
        content_type = content.get('contentType', 'Unknown')
306
        if content_type not in deal_stage_engagement[deal_stage]['content_types']:
307
            deal_stage_engagement[deal_stage]['content_types'][content_type] = 0
308
        deal_stage_engagement[deal_stage]['content_types'][content_type] += 1
309

310
print("Content Engagement by Deal Stage:")
311
for stage, data in deal_stage_engagement.items():
312
    unique_deals = len(data['deals'])
313
    avg_content_views = data['total_content_views'] / max(unique_deals, 1)
314
    print(f"\n{stage}:")
315
    print(f"  Deals: {unique_deals}")
316
    print(f"  Avg content views per deal: {avg_content_views:.1f}")
317
    print(f"  Popular content types: {dict(sorted(data['content_types'].items(), key=lambda x: x[1], reverse=True)[:3])}")
318
```
319

320
### Product Analytics
321

322
```python
323
from source_hubspot.streams import ProductsWebAnalytics
324

325
products_analytics = ProductsWebAnalytics(
326
    api=api,
327
    start_date="2023-01-01T00:00:00Z",
328
    credentials=credentials
329
)
330

331
# Track product page engagement
332
product_engagement = {}
333

334
for record in products_analytics.read_records(sync_mode="full_refresh"):
335
    product_id = record.get('productId')
336
    page_views = record.get('pageViews', 0)
337
    unique_visitors = record.get('uniqueVisitors', 0)
338
    conversion_rate = record.get('conversionRate', 0)
339
    
340
    if product_id:
341
        product_engagement[product_id] = {
342
            'page_views': page_views,
343
            'unique_visitors': unique_visitors,
344
            'conversion_rate': conversion_rate * 100,  # Convert to percentage
345
            'engagement_rate': (unique_visitors / max(page_views, 1)) * 100
346
        }
347

348
# Identify high-performing products
349
print("Product Performance Analytics:")
350
sorted_products = sorted(
351
    product_engagement.items(),
352
    key=lambda x: x[1]['conversion_rate'],
353
    reverse=True
354
)
355

356
for product_id, data in sorted_products[:5]:
357
    print(f"Product {product_id}:")
358
    print(f"  Page Views: {data['page_views']}")
359
    print(f"  Unique Visitors: {data['unique_visitors']}")
360
    print(f"  Conversion Rate: {data['conversion_rate']:.2f}%")
361
    print(f"  Engagement Rate: {data['engagement_rate']:.2f}%")
362
```
363

364
## Configuration
365

366
### Enabling Experimental Streams
367

368
Web analytics streams are only available when experimental streams are enabled:
369

370
```python
371
config = {
372
    # ... other configuration
373
    "enable_experimental_streams": True
374
}
375
```
376

377
### Stream Dependencies
378

379
Web analytics streams depend on their parent streams:
380
- ContactsWebAnalytics requires Contacts stream data
381
- CompaniesWebAnalytics requires Companies stream data
382
- DealsWebAnalytics requires Deals stream data
383
- etc.
384

385
## Data Structure
386

387
Web analytics streams typically return records with the following structure:
388

389
```python { .api }
390
# Example web analytics record
391
{
392
    "objectId": str,          # ID of the associated object (contact, company, etc.)
393
    "objectType": str,        # Type of associated object
394
    "sessionData": {
395
        "sessionId": str,
396
        "pageViews": int,
397
        "sessionDurationMs": int,
398
        "bounceRate": float,
399
        "entryPage": str,
400
        "exitPage": str
401
    },
402
    "engagementMetrics": {
403
        "engagementScore": float,
404
        "interactionCount": int,
405
        "contentViews": List[Dict],
406
        "formSubmissions": int
407
    },
408
    "trafficSource": {
409
        "source": str,
410
        "medium": str,
411
        "campaign": str,
412
        "referrer": str
413
    },
414
    "timestamp": int,         # Unix timestamp
415
    "customEvents": List[Dict] # Custom event tracking data
416
}
417
```
418

419
## Limitations
420

421
- **Experimental Status**: These streams are experimental and may change or be removed
422
- **Data Availability**: Analytics data availability depends on HubSpot tracking implementation
423
- **Performance**: Web analytics streams may have different performance characteristics
424
- **OAuth Scopes**: May require additional scopes beyond standard CRM permissions